baha/skyline-apiserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add more for contributor introduction

Browse Source 
1. Add more for contributor introduction
2. Cleanup README.rst
3. Update settings.rst

Change-Id: Id1736bec1b337228f81a9863f9fb0fd80ac186d5
This commit is contained in:
Boxiang Zhu 2022-08-22 16:47:16 +08:00
parent 6ca6f7dd1d
commit 21aa0719b7
11 changed files with 415 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
README.rst
View File

@ -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 <https://bugs.launchpad.net/skyline-apiserver>`__ You can raise bugs on `Launchpad <https://bugs.launchpad.net/skyline-apiserver>`__
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 Devstack Integration
-------------------- --------------------
`Fast integration with Devstack to build an Fast integration with `devstack <./devstack/README.rst>`__ to build an environment.
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

6
doc/source/admin/index.rst
View File

@ -1,6 +0,0 @@
====================
Administration Guide
====================
.. toctree::
:maxdepth: 1

10
doc/source/common/glossary.rst
View File

@ -3,3 +3,13 @@
======== ========
Glossary 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.

6
doc/source/configuration/settings.rst
View File

@ -22,6 +22,7 @@ file ``skyline.yaml.sample`` in ``etc`` directory.
prometheus_endpoint: http://localhost:9091 prometheus_endpoint: http://localhost:9091
secret_key: aCtmgbcUqYUy_HNVg5BDXCaeJgJQzHJXwqbXr0Nmb2o secret_key: aCtmgbcUqYUy_HNVg5BDXCaeJgJQzHJXwqbXr0Nmb2o
session_name: session session_name: session
ssl_enabled: true
openstack: openstack:
base_domains: base_domains:
- heat_user_domain - heat_user_domain
@ -51,6 +52,10 @@ file ``skyline.yaml.sample`` in ``etc`` directory.
placement: placement placement: placement
sharev2: manilav2 sharev2: manilav2
volumev3: cinder volumev3: cinder
sso_enabled: false
sso_protocols:
- openid
sso_region: RegionOne
system_admin_roles: system_admin_roles:
- admin - admin
- system_admin - system_admin
@ -87,4 +92,3 @@ file ``skyline.yaml.sample`` in ``etc`` directory.
- nvidia_t4 - nvidia_t4
usb_models: usb_models:
- usb_c - usb_c

78
doc/source/contributor/backporting.rst Normal file
View File

@ -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
<https://docs.openstack.org/project-team-guide/stable-branches.html>`_.
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.

127
doc/source/contributor/development.environment.rst Normal file
View File

@ -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 <https://pypi.org/project/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

101
doc/source/contributor/documentation.rst Normal file
View File

@ -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
<https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_
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/<release>``. 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.

23
doc/source/contributor/index.rst
View File

@ -11,6 +11,29 @@ Getting Started
:maxdepth: 2 :maxdepth: 2
contributing 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 Other Resources
--------------- ---------------

70
doc/source/contributor/releases.rst Normal file
View File

@ -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
<https://docs.openstack.org/project-team-guide/stable-branches.html>`_
section of the
`OpenStack Project Team Guide
<https://docs.openstack.org/project-team-guide/index.html>`_
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
<https://docs.openstack.org/project-team-guide/stable-branches.html>`_. 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
<https://review.opendev.org/admin/groups/5c75219bf2ace95cdea009c82df26ca199e04d59,members>`_.

2
doc/source/index.rst
View File

@ -46,8 +46,6 @@ How to use Skyline APIServer in your own projects.
install/index install/index
configuration/index configuration/index
User Documentation <user/index>
admin/index
Contributor Docs Contributor Docs
================ ================

6
doc/source/user/index.rst
View File

@ -1,6 +0,0 @@
========================================
User Documentation
========================================
.. toctree::
:maxdepth: 1