diff --git a/README.rst b/README.rst index e69b2038..c1e7dabb 100644 --- a/README.rst +++ b/README.rst @@ -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 `__ - ``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. diff --git a/doc/source/contributor/backporting.rst b/doc/source/contributor/backporting.rst new file mode 100644 index 00000000..6efa6e6f --- /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 Console 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-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. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 00000000..44098d24 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,193 @@ +============================ +So You Want to Contribute... +============================ + +For general information on contributing to OpenStack, please check out the +`contributor guide `_ 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 + `_ + 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 + `_ . + +The current Skyline Console project Project Team Lead (PTL) is listed in the +`Skyline Console project reference +`_ +maintained by the OpenStack Technical Committee. + +All common PTL duties are enumerated in the `PTL guide +`_. + +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 + `_. + + 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 diff --git a/doc/source/contributor/development.environment.rst b/doc/source/contributor/development.environment.rst new file mode 100644 index 00000000..5288827c --- /dev/null +++ b/doc/source/contributor/development.environment.rst @@ -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 `__ +- ``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 diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst new file mode 100644 index 00000000..de442e3b --- /dev/null +++ b/doc/source/contributor/documentation.rst @@ -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 +`_ +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/``. 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/gerrit.rst b/doc/source/contributor/gerrit.rst new file mode 100644 index 00000000..2f1a95f7 --- /dev/null +++ b/doc/source/contributor/gerrit.rst @@ -0,0 +1,4 @@ +.. _reviewing-skyline-console: + +Code Reviews +============ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 00d22a95..ef1ccb1e 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -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` diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst new file mode 100644 index 00000000..ed195fbd --- /dev/null +++ b/doc/source/contributor/releasenotes.rst @@ -0,0 +1,4 @@ +.. _release-notes: + +Release notes +============= diff --git a/doc/source/contributor/releases.rst b/doc/source/contributor/releases.rst new file mode 100644 index 00000000..aefe0ab3 --- /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-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 +`_. 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/glossary.rst b/doc/source/glossary.rst index 0c1e38e7..a65818e4 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -3,3 +3,6 @@ ======== Glossary ======== + +This glossary offers a list of terms and definitions to define a + vocabulary for Skyline Console concepts.