openstack/skyline-console
Code Issues Proposed changes

docs: Add contributor introduction

Browse Source 
Add contributor introduction

Change-Id: I152bef5717099c2a7b120d7b55ae8ccac7a0b05a
This commit is contained in:
yangsngshaoxue 2022-08-24 18:21:58 +08:00
parent b211ebca9c
commit 3f1dba0b91
10 changed files with 617 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.rst
View File

@ -66,7 +66,7 @@ Take CentOS as an example
npm install -g yarn
- Install the project dependency under the root directory, with
``package.json``\ in the same place.
``package.json`` in the same place.
.. code:: shell
@ -83,7 +83,7 @@ Under the root directory, with ``package.json`` in the same place.
- ``yarn run mock``: Use the mock interface of
`rap2 <http://rap2.taobao.org/>`__
- ``yarn run dev``: To use the actual interface, please change the
“http://pre.xxx.com” in line 47 into the real address in file
"http://pre.xxx.com" in line 47 into the real address in file
``webpack.dev.js``.
- ``yarn run build``: Build packages and then you can hand over the
contents of the generated *dist* directory to the back end.

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 Console 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-console 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.

193
doc/source/contributor/contributing.rst Normal file
View File

@ -0,0 +1,193 @@
============================
So You Want to Contribute...
============================
For general information on contributing to OpenStack, please check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
It covers all the basics that are common to all OpenStack projects: the
accounts you need, the basics of interacting with our Gerrit review system, how
we communicate as a community, etc.
Below will cover the more project specific information you need to get started
with the skyline-console project, which is responsible for the following
OpenStack deliverables:
skyline-console
| The OpenStack Modern Dashboard - front-end.
| code: https://opendev.org/openstack/skyline-console
| docs: https://docs.openstack.org/skyline-console/latest/
| Launchpad: https://launchpad.net/skyline-apiserver
Communication
~~~~~~~~~~~~~
IRC
We use IRC *a lot*. You will, too. You can find infomation about what
IRC network OpenStack uses for communication (and tips for using IRC)
in the `Setup IRC
<https://docs.openstack.org/contributors/common/irc.html>`_
section of the main `OpenStack Contributor Guide`.
People working on the Skyline Console project may be found in the
``#openstack-skyline`` IRC channel during working hours
in their timezone. The channel is logged, so if you ask a question
when no one is around, you can check the log to see if it's been
answered: http://eavesdrop.openstack.org/irclogs/%23openstack-skyline/
weekly meeting
.. note::
Now we have not weekly meeting, we will have it in the future.
mailing list
We use the openstack-discuss@lists.openstack.org mailing list for
asynchronous discussions or to communicate with other OpenStack teams.
Use the prefix ``[skyline]`` in your subject line (it's a high-volume
list, so most people use email filters).
More information about the mailing list, including how to subscribe
and read the archives, can be found at:
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
Contacting the Core Team
~~~~~~~~~~~~~~~~~~~~~~~~
The skyline-core team is an active group of contributors who are responsible
for directing and maintaining the skyline-console project. As a new
contributor, your interaction with this group will be mostly through code
reviews, because only members of skyline-core can approve a code change to be
merged into the code repository.
You can learn more about the role of core reviewers in the OpenStack
governance documentation:
https://docs.openstack.org/contributors/common/governance.html#core-reviewer
The membership list of skyline-core is maintained in gerrit:
https://review.opendev.org/admin/groups/1fe65032c39f1d459327b010730627a904d7b793,members
Project Team Lead
~~~~~~~~~~~~~~~~~
For each development cycle, Skyline Console project Active Technical
Contributors (ATCs) elect a Project Team Lead who is responsible for running
midcycles, and skyline-console sessions at the Project Team Gathering for
that cycle (and who is also ultimately responsible for everything else the
project does).
* You automatically become an ATC by making a commit to one of the
skyline-console deliverables. Other people who haven't made a commit,
but have contributed to the project in other ways (for example, making good
bug reports) may be recognized as "extra-ATCs" and obtain voting privileges.
If you are such a person, contact the current PTL before the "Extra-ATC
freeze" indicated on the current development cycle schedule (which you can
find from the `OpenStack Releases homepage
<https://releases.openstack.org/index.html>`_ .
The current Skyline Console project Project Team Lead (PTL) is listed in the
`Skyline Console project reference
<https://governance.openstack.org/tc/reference/projects/skyline.html>`_
maintained by the OpenStack Technical Committee.
All common PTL duties are enumerated in the `PTL guide
<https://docs.openstack.org/project-team-guide/ptl.html>`_.
New Feature Planning
~~~~~~~~~~~~~~~~~~~~
The Skyline Console project uses "blueprints" to track new features. Here's a
quick rundown of what they are and how the Skyline Console project uses them.
blueprints
| Exist in Launchpad, where they can be targeted to release milestones.
| You file one at https://blueprints.launchpad.net/skyline-apiserver
Feel free to ask in ``#openstack-skyline`` if you have an idea you want to
develop and you're not sure whether it requires a blueprint *and* a spec or
simply a blueprint.
The Skyline Console project observes the following deadlines. For the current
development cycle, the dates of each (and a more detailed description)
may be found on the release schedule, which you can find from:
https://releases.openstack.org/
* bp freeze (all bps must be approved by this date)
* new feature status checkpoint
Task Tracking
~~~~~~~~~~~~~
We track our tasks in Launchpad. See the top of the page for the URL of
Skyline Console project deliverable.
If you're looking for some smaller, easier work item to pick up and get started
on, search for the 'low-hanging-fruit' tag in the Bugs section.
When you start working on a bug, make sure you assign it to yourself.
Otherwise someone else may also start working on it, and we don't want to
duplicate efforts. Also, if you find a bug in the code and want to post a
fix, make sure you file a bug (and assign it to yourself!) just in case someone
else comes across the problem in the meantime.
Reporting a Bug
~~~~~~~~~~~~~~~
You found an issue and want to make sure we are aware of it? You can do so in
the Launchpad space for the affected deliverable:
* skyline-console: https://bugs.launchpad.net/skyline-apiserver
Getting Your Patch Merged
~~~~~~~~~~~~~~~~~~~~~~~~~
Before your patch can be merged, it must be *reviewed* and *approved*.
The Skyline Console project policy is that a patch must have two +2s before
it can be merged. (Exceptions are documentation changes, which require only a
single +2, for which the PTL may require more than two +2s, depending on the
complexity of the proposal.) Only members of the skyline-core team can vote +2
(or -2) on a patch, or approve it.
.. note::
Although your contribution will require reviews by members of
skyline-core, these aren't the only people whose reviews matter.
Anyone with a gerrit account can post reviews, so you can ask
other developers you know to review your code ... and you can
review theirs. (A good way to learn your way around the codebase
is to review other people's patches.)
If you're thinking, "I'm new at this, how can I possibly provide
a helpful review?", take a look at `How to Review Changes the
OpenStack Way
<https://docs.openstack.org/project-team-guide/review-the-openstack-way.html>`_.
There are also some Skyline Console project specific reviewing
guidelines in the :ref:`reviewing-skyline-console` section of the
Skyline Console Contributor Guide.
In addition, some changes may require a release note. Any patch that
changes functionality, adds functionality, or addresses a significant
bug should have a release note. You can find more information about
how to write a release note in the :ref:`release-notes` section of the
Skyline Console Contributors Guide.
.. note::
Keep in mind that the best way to make sure your patches are reviewed in
a timely manner is to review other people's patches. We're engaged in a
cooperative enterprise here.
If your patch has a -1 from Zuul, you should fix it right away, because
people are unlikely to review a patch that is failing the CI system.
How long it may take for your review to get attention will depend on the
current project priorities. For example, the feature freeze is at the
third milestone of each development cycle, so feature patches have the
highest priority just before M-3. These dates are clearly noted on the
release schedule for the current release, which you can find
from https://releases.openstack.org/
You can see who's been doing what with Skyline Console recently in
Stackalytics:
https://www.stackalytics.io/report/activity?module=skyline-group

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

@ -0,0 +1,117 @@
Setting Up a Development Environment
====================================
This page describes how to setup a working development environment that
can be used in developing skyline-console on Linux. 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-console unit
tests.
Linux Systems
-------------
Install system dependencies
- `Ubuntu/Debian`
.. code:: shell
sudo apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb
- `CentOS`
.. code:: shell
yum install -y xorg-x11-server-Xvfb gtk2-devel gtk3-devel libnotify-devel GConf2 nss libXScrnSaver alsa-lib
Getting the code
----------------
Grab the code::
git clone https://opendev.org/openstack/skyline-console.git
cd skyline-console
Setup Your Local Development Env
--------------------------------
Take CentOS as an example
- Install nvm ( version control system for nodejs )
.. code:: shell
wget -P /root/ --tries=10 --retry-connrefused --waitretry=60 --no-dns-cache --no-cache https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh
bash /root/install.sh
. /root/.nvm/nvm.sh
- Install nodejs
.. code:: shell
NODE_VERSION=erbium
nvm install --lts=$NODE_VERSION
nvm alias default lts/$NODE_VERSION
nvm use default
- Verify nodejs and npm versions
.. code:: shell
node -v
# v12.*.*
npm -v
# 6.*.*
- Install yarn
.. code:: shell
npm install -g yarn
- Install the project dependency under the root directory, with
``package.json`` in the same place.
.. code:: shell
yarn install
After those steps, please just wait until the installation is
complete.
You can also use the following commands:
- ``yarn run mock``: Use the mock interface of
`rap2 <http://rap2.taobao.org/>`__
- ``yarn run dev``: To use the actual interface, please change the
"http://pre.xxx.com" in line 47 into the real address in file
``webpack.dev.js``.
- ``yarn run build``: Build packages and then you can hand over the
contents of the generated *dist* directory to the back end.
Running tests
-------------
- e2e tests
.. code:: shell
yarn run test:e2e
- unit tests
.. code:: shell
yarn run test:unit
Contributing Your Work
----------------------
Once your work is complete you may wish to contribute it to the project.
skyline-console 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

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

@ -0,0 +1,98 @@
Contributing Documentation to Skyline Console
==============================================
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 Console'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``.
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 Console's Documentation Page at
https://docs.openstack.org/skyline-console/latest\ . When a new release is
cut a snapshot of that documentation will be kept at
``https://docs.openstack.org/skyline-console/<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.

4
doc/source/contributor/gerrit.rst Normal file
View File

@ -0,0 +1,4 @@
.. _reviewing-skyline-console:
Code Reviews
============

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

@ -2,5 +2,52 @@
Contributor Documentation
===========================
In this section you will find information on how to contribute to
skyline-console. Content includes architectural overviews, tips and tricks
for setting up a development environment.
Getting Started
---------------
.. toctree::
:maxdepth: 1
: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
---------------
.. toctree::
:maxdepth: 3
gerrit
releasenotes
.. only:: html
Indices and tables
------------------
* :ref:`genindex`
* :ref:`search`

4
doc/source/contributor/releasenotes.rst Normal file
View File

@ -0,0 +1,4 @@
.. _release-notes:
Release notes
=============

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-console* 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>`_.

3
doc/source/glossary.rst
View File

@ -3,3 +3,6 @@
========
Glossary
========
This glossary offers a list of terms and definitions to define a
vocabulary for Skyline Console concepts.