From 21aa0719b7a5fd541a07ea423c7c9cec54dfe792 Mon Sep 17 00:00:00 2001 From: Boxiang Zhu Date: Mon, 22 Aug 2022 16:47:16 +0800 Subject: [PATCH] docs: Add more for contributor introduction 1. Add more for contributor introduction 2. Cleanup README.rst 3. Update settings.rst Change-Id: Id1736bec1b337228f81a9863f9fb0fd80ac186d5 --- README.rst | 100 +------------- doc/source/admin/index.rst | 6 - doc/source/common/glossary.rst | 10 ++ doc/source/configuration/settings.rst | 6 +- doc/source/contributor/backporting.rst | 78 +++++++++++ .../contributor/development.environment.rst | 127 ++++++++++++++++++ doc/source/contributor/documentation.rst | 101 ++++++++++++++ doc/source/contributor/index.rst | 23 ++++ doc/source/contributor/releases.rst | 70 ++++++++++ doc/source/index.rst | 2 - doc/source/user/index.rst | 6 - 11 files changed, 415 insertions(+), 114 deletions(-) delete mode 100644 doc/source/admin/index.rst create mode 100644 doc/source/contributor/backporting.rst create mode 100644 doc/source/contributor/development.environment.rst create mode 100644 doc/source/contributor/documentation.rst create mode 100644 doc/source/contributor/releases.rst delete mode 100644 doc/source/user/index.rst diff --git a/README.rst b/README.rst index 0889cb8..0a5599e 100644 --- a/README.rst +++ b/README.rst @@ -29,105 +29,7 @@ If you'd like to run from the master branch, you can clone the git repo: You can raise bugs on `Launchpad `__ -Develop Skyline-apiserver -------------------------- - -**Support Linux & Mac OS (Recommend Linux OS) (Because uvloop & cython)** - -Dependent tools -~~~~~~~~~~~~~~~ - - Use the new feature Context Variables of python37 & uvloop(0.15.0+ - requires python37). Considering that most systems do not support - python37, we choose to support python38 at least. - -- make >= 3.82 -- python >= 3.8 -- node >= 10.22.0 (Optional if you only develop with apiserver) -- yarn >= 1.22.4 (Optional if you only develop with apiserver) - -Install & Run -~~~~~~~~~~~~~ - -1. Installing dependency packages - - .. code:: bash - - tox -e venv - -2. Set skyline.yaml config file - - .. code:: bash - - cp etc/skyline.yaml.sample etc/skyline.yaml - export OS_CONFIG_DIR=$(pwd)/etc - - Maybe you should change the params with your real environment as - followed: - - .. code:: yaml - - - database_url - - keystone_url - - default_region - - interface_type - - system_project_domain - - system_project - - system_user_domain - - system_user_name - - system_user_password - - .. - - If you set such as ``sqlite:////tmp/skyline.db`` for - ``database_url`` , just do as followed. If you set such as - ``mysql://root:root@localhost:3306/skyline`` for ``database_url`` - , you should refer to steps ``1`` and ``2`` of the chapter - ``Deployment with MariaDB`` at first. - -3. Init skyline database - - .. code:: bash - - source .tox/venv/bin/activate - make db_sync - deactivate - -4. Run skyline-apiserver - - .. code:: console - - $ source .tox/venv/bin/activate - $ uvicorn --reload --reload-dir skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app - - INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) - INFO: Started reloader process [154033] using statreload - INFO: Started server process [154037] - INFO: Waiting for application startup. - INFO: Application startup complete. - - You can now access the online API documentation: - ``http://127.0.0.1:28000/docs``. - - Or, you can launch debugger with ``.vscode/lauch.json`` with vscode. - -5. Build Image - - .. code:: bash - - make build - Devstack Integration -------------------- -`Fast integration with Devstack to build an -environment. <./devstack/README.rst>`__ - -Kolla Ansible Deployment ------------------------- - -`Kolla Ansible to build an environment. <./kolla/README.md>`__ - -|image1| - -.. |image1| image:: docs/images/nine-color-deer-64.png +Fast integration with `devstack <./devstack/README.rst>`__ to build an environment. diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst deleted file mode 100644 index b4910e5..0000000 --- a/doc/source/admin/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -==================== -Administration Guide -==================== - -.. toctree:: - :maxdepth: 1 diff --git a/doc/source/common/glossary.rst b/doc/source/common/glossary.rst index 0c1e38e..77c341c 100644 --- a/doc/source/common/glossary.rst +++ b/doc/source/common/glossary.rst @@ -3,3 +3,13 @@ ======== Glossary ======== + +This glossary offers a list of terms and definitions to define a +vocabulary for Skyline APIServer concepts. + +.. glossary:: + + Schemas + + Provide a description of the data that is expected to be returned + or request. diff --git a/doc/source/configuration/settings.rst b/doc/source/configuration/settings.rst index 5ffac36..a4a100b 100644 --- a/doc/source/configuration/settings.rst +++ b/doc/source/configuration/settings.rst @@ -22,6 +22,7 @@ file ``skyline.yaml.sample`` in ``etc`` directory. prometheus_endpoint: http://localhost:9091 secret_key: aCtmgbcUqYUy_HNVg5BDXCaeJgJQzHJXwqbXr0Nmb2o session_name: session + ssl_enabled: true openstack: base_domains: - heat_user_domain @@ -51,6 +52,10 @@ file ``skyline.yaml.sample`` in ``etc`` directory. placement: placement sharev2: manilav2 volumev3: cinder + sso_enabled: false + sso_protocols: + - openid + sso_region: RegionOne system_admin_roles: - admin - system_admin @@ -87,4 +92,3 @@ file ``skyline.yaml.sample`` in ``etc`` directory. - nvidia_t4 usb_models: - usb_c - diff --git a/doc/source/contributor/backporting.rst b/doc/source/contributor/backporting.rst new file mode 100644 index 0000000..552d259 --- /dev/null +++ b/doc/source/contributor/backporting.rst @@ -0,0 +1,78 @@ +================= +Backporting a Fix +================= + +From time to time, you may find a bug that's been fixed in master, and you'd +like to have that fix in the release you're currently using (for example, +Wallaby). What you want to do is propose a **backport** of the fix. + +.. note:: + The Skyline APIServer project observes the OpenStack `Stable Branch Policy + `_. + Thus, not every change in master is backportable to the stable branches. + In particular, features are *never* backportable. A really complicated + bugfix may not be backportable if what it fixes is low-occurrence and + there's a high risk that it may cause a regression elsewhere in the + software. + + How can you tell? Ask in the ``#openstack-skyline`` channel on IRC. + +Since we use git for source code version control, backporting is done by +*cherry-picking* a change that has already been merged into one branch into +another branch. The gerrit web interface makes it really easy to do this. +In fact, maybe *too* easy. Here are some guidelines: + +* Before you cherry-pick a change, make sure it has already **merged** + to master. If the change hasn't merged yet, it may require further + revision, and the commit you've cherry-picked won't be the correct + commit to backport. + +* Backports must be done in *reverse chronological order*. Since + OpenStack releases are named alphabetically, this means reverse + alphabetical order: ``stable/yoga``, ``stable/xena``, etc. + +* The cherry-pick must have **merged** into the closest most recent branch + before it will be considered for a branch, that is, a cherry-pick to + ``stable/xena`` will **not** be considered until it has merged into + ``stable/yoga`` first. + + * This is because sometimes a backport requires revision along the + way. For example, different OpenStack releases support different + versions of Python. So if a fix uses a language feature introduced + in Python 3.8, it will merge just fine into current master (during zed + development), but it will not pass unit tests in ``stable/yoga`` + (which supports Python 3.6). Likewise, if you already cherry-picked + the patch from master directly to ``stable/xena``, it won't pass tests + there either (because xena also supports Python 3.6). + + So it's better to follow the policy and wait until the patch is merged + into ``stable/yoga`` *before* you propose a backport to ``stable/xena``. + +* You can propose backports directly from git instead of using the gerrit + web interface, but if you do, you must include the fact that it's a + cherry-pick in the commit message. Gerrit does this automatically for + you *if you cherry-pick from a merged commit* (which is the only kind of + commit you should cherry-pick from in Gerrit); git will do it for you if + you use the ``-x`` flag when you do a manual cherry-pick. + + This will keep the history of this backport intact as it goes from + branch to branch. We want this information to be in the commit message + and to be accurate, because if the fix causes a regression (which is + always possible), it will be helpful to the poor sucker who has to fix + it to know where this code came from without digging through a bunch of + git history. + +If you have questions about any of this, or if you have a bug to fix that +is only present in one of the stable branches, ask for advice in +``#openstack-skyline`` on IRC. + +Backport CI Testing +------------------- + +Like all code changes, backports should undergo continuous integration +testing. This is done automatically by Zuul for changes that affect the +main skyline-apiserver code. + +This shouldn't be a big deal because presumably you've done local +testing with your backend to ensure that the code works as expected in a +stable branch; we're simply asking that this be documented on the backport. diff --git a/doc/source/contributor/development.environment.rst b/doc/source/contributor/development.environment.rst new file mode 100644 index 0000000..acd5f3f --- /dev/null +++ b/doc/source/contributor/development.environment.rst @@ -0,0 +1,127 @@ +Setting Up a Development Environment +==================================== + +This page describes how to setup a working Python development environment that +can be used in developing skyline-apiserver on Ubuntu. These instructions +assume you're already familiar with git. Refer to GettingTheCode_ for +additional information. + +.. _GettingTheCode: https://wiki.openstack.org/wiki/Getting_The_Code + +Following these instructions will allow you to run the skyline-apiserver unit +tests. Running skyline-apiserver is currently only supported on Linux(recommend +Ubuntu 20.04). + +Virtual environments +-------------------- + +Skyline-apiserver development uses `virtualenv `__ +to track and manage Python dependencies while in development and testing. This +allows you to install all of the Python package dependencies in a virtual +environment or "virtualenv" (a special subdirectory of your skyline-apiserver +directory), instead of installing the packages at the system level. + +.. note:: + + Virtualenv is useful for running the unit tests, but is not + typically used for full integration testing or production usage. + +Linux Systems +------------- + +Install the prerequisite packages. + +On Ubuntu20.04-64:: + + sudo apt-get install libssl-dev python3-pip libmysqlclient-dev libpq-dev libffi-dev + +To get a full python3 development environment, the two python3 packages need to +be added to the list above:: + + python3-dev python3-pip + +Getting the code +---------------- +Grab the code:: + + git clone https://opendev.org/openstack/skyline-apiserver.git + cd skyline-apiserver + +Running unit tests +------------------ + +The preferred way to run the unit tests is using ``tox``. It executes tests in +isolated environment, by creating separate virtualenv and installing +dependencies from the ``requirements.txt`` and ``test-requirements.txt`` files, +so the only package you install is ``tox`` itself:: + + sudo pip install tox + +Run the unit tests by doing:: + + tox -e py38 + +Setup Your Local Development Env +-------------------------------- + +#. Installing dependency packages + + .. code:: bash + + tox -e venv + +#. Set skyline.yaml config file + + .. code:: bash + + cp etc/skyline.yaml.sample etc/skyline.yaml + export OS_CONFIG_DIR=$(pwd)/etc + + Maybe you should change the params with your real environment as + followed: + + .. code:: yaml + + - database_url + - keystone_url + - default_region + - interface_type + - system_project_domain + - system_project + - system_user_domain + - system_user_name + - system_user_password + +#. Init skyline database + + .. code:: bash + + source .tox/venv/bin/activate + make db_sync + deactivate + +#. Run skyline-apiserver + + .. code:: console + + $ source .tox/venv/bin/activate + $ uvicorn --reload --reload-dir skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app + + INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) + INFO: Started reloader process [154033] using statreload + INFO: Started server process [154037] + INFO: Waiting for application startup. + INFO: Application startup complete. + + You can now access the online API documentation: ``http://127.0.0.1:28000/docs``. + + Or, you can launch debugger with ``.vscode/lauch.json`` with vscode. + +Contributing Your Work +---------------------- + +Once your work is complete you may wish to contribute it to the project. +Skyline-apiserver uses the Gerrit code review system. For information on +how to submit your branch to Gerrit, see GerritWorkflow_. + +.. _GerritWorkflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst new file mode 100644 index 0000000..644daf1 --- /dev/null +++ b/doc/source/contributor/documentation.rst @@ -0,0 +1,101 @@ +Contributing Documentation to Skyline APIServer +=============================================== + +This page provides guidance on how to provide documentation for those +who may not have previously been active writing documentation for +OpenStack. + +Documentation Content +--------------------- + +To keep the documentation consistent across projects, and to maintain +quality, please follow the OpenStack `Writing style +`_ +guide. + +Using RST +--------- + +OpenStack documentation uses reStructuredText to write documentation. +The files end with a ``.rst`` extension. The ``.rst`` files are then +processed by Sphinx to build HTML based on the RST files. + +.. note:: + Files that are to be included using the ``.. include::`` directive in an + RST file should use the ``.inc`` extension. If you instead use the ``.rst`` + this will result in the RST file being processed twice during the build and + cause Sphinx to generate a warning during the build. + +reStructuredText is a powerful language for generating web pages. The +documentation team has put together an `RST conventions`_ page with information +and links related to RST. + +.. _RST conventions: https://docs.openstack.org/doc-contrib-guide/rst-conv.html + +Building Skyline APIServer's Documentation +------------------------------------------ + +To build documentation the following command should be used: + +.. code-block:: console + + tox -e docs + +When building documentation it is important to also run docs. + +.. note:: + + The tox documentation jobs (docs, releasenotes) are set up to treat Sphinx + warnings as errors. This is because many Sphinx warnings result in + improperly formatted pages being generated, so we prefer to fix those right + now, instead of waiting for someone to report a docs bug. + +During the documentation build a number of things happen: + +* All of the RST files under ``doc/source`` are processed and built. + + * The openstackdocs theme is applied to all of the files so that they + will look consistent with all the other OpenStack documentation. + * The resulting HTML is put into ``doc/build/html``. + +* All of Skyline APIServer's ``.py`` files are processed and the docstrings are + used to generate the files under ``doc/source/contributor/api`` + +After the build completes the results may be accessed via a web browser in +the ``doc/build/html`` directory structure. + +Review and Release Process +-------------------------- +Documentation changes go through the same review process as all other changes. + +.. note:: + + Reviewers can see the resulting web page output by clicking on + ``openstack-tox-docs`` in the "Zuul check" table on the review, + and then look for "Artifacts" > "Docs preview site". + + This is also true for the ``build-openstack-releasenotes`` check jobs. + +Once a patch is approved it is immediately released to the docs.openstack.org +website and can be seen under Skyline APIServer's Documentation Page at +https://docs.openstack.org/skyline-apiserver/latest\ . When a new release is +cut a snapshot of that documentation will be kept at +``https://docs.openstack.org/skyline-apiserver/``. Changes from +master can be backported to previous branches if necessary. + +Finding something to contribute +------------------------------- + +If you are reading the documentation and notice something incorrect or +undocumented, you can directly submit a patch following the advice set +out below. + +There are also documentation bugs that other people have noticed that +you could address: + +* https://bugs.launchpad.net/skyline-apiserver/+bugs?field.tag=doc + +.. note:: + If you don't see a bug listed, you can also try the tag 'docs' or + 'documentation'. We tend to use 'doc' as the appropriate tag, but + occasionally a bug gets tagged with a variant. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 90293bc..2ad4bf1 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -11,6 +11,29 @@ Getting Started :maxdepth: 2 contributing + backporting + releases + documentation + +Writing Release Notes +--------------------- + +Please follow the format, it will make everyone's life easier. + +.. toctree:: + :maxdepth: 2 + + releasenotes + +.. _programming-howtos: + +Programming HowTos and Tutorials +-------------------------------- + +.. toctree:: + :maxdepth: 2 + + development.environment Other Resources --------------- diff --git a/doc/source/contributor/releases.rst b/doc/source/contributor/releases.rst new file mode 100644 index 0000000..f2d2441 --- /dev/null +++ b/doc/source/contributor/releases.rst @@ -0,0 +1,70 @@ +Skyline Project Releases +======================== + +The Skyline project follows the OpenStack 6 month development cycle, +at the end of which a new stable branch is created from master, and master +becomes the development branch for the next development cycle. + +Because many OpenStack consumers don't move as quickly as OpenStack +development, we backport appropriate bugfixes from master into the stable +branches and create new releases for consumers to use ... for a while. +See the `Stable Branches +`_ +section of the +`OpenStack Project Team Guide +`_ +for details about the timelines. + +What follows is information about the Skyline project and its releases. + +Where Stuff Is +~~~~~~~~~~~~~~ + +The Skyline Project Deliverables +-------------------------------- + +https://governance.openstack.org/tc/reference/projects/skyline.html#deliverables + +The Code Repositories +--------------------- + +* https://opendev.org/openstack/skyline-apiserver +* https://opendev.org/openstack/skyline-console + +All Skyline Project Releases +---------------------------- + +https://releases.openstack.org/teams/skyline.html + +How Stuff Works +~~~~~~~~~~~~~~~ + +Releases from Master +-------------------- + +Releases from **master** for *skyline-apiserver* follow the 'cycle-with-rc' +release model. + +* The 'cycle-with-rc' model describes projects that produce a single release + at the end of the cycle, with one or more release candidates (RC) close to + the end of the cycle and optional development milestone betas published on + a per-project need. + +For more information about the release models and deliverable types: +https://releases.openstack.org/reference/release_models.html + +Branching +--------- + +All Skyline project deliverables follow the `OpenStack stable branch policy +`_. Briefly, + +* The stable branches are intended to be a safe source of fixes for high + impact bugs and security issues which have been fixed on master since a + given release. +* Stable branches are cut from the last release of a given deliverable, at + the end of the common 6-month development cycle. + +While anyone may propose a release, releases must be approved by +the `OpenStack Release Managers +`_. diff --git a/doc/source/index.rst b/doc/source/index.rst index bb40bc3..a84ccf0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -46,8 +46,6 @@ How to use Skyline APIServer in your own projects. install/index configuration/index - User Documentation - admin/index Contributor Docs ================ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst deleted file mode 100644 index 8fcc7e0..0000000 --- a/doc/source/user/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -======================================== -User Documentation -======================================== - -.. toctree:: - :maxdepth: 1