diff --git a/doc/requirements.txt b/doc/requirements.txt index 44a88b6..aabd660 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,4 @@ pbr openstackdocstheme>=1.11.0 # Apache-2.0 sphinx>=1.6.2 # BSD +doc8>=0.6.0 # Apache-2.0 diff --git a/doc/source/dependency-management.rst b/doc/source/dependency-management.rst index 33fd593..238643d 100644 --- a/doc/source/dependency-management.rst +++ b/doc/source/dependency-management.rst @@ -353,8 +353,8 @@ bot will generate an appropriate change itself. Ask in #openstack-infra if the bot needs to be run more quickly. Otherwise the change may be the result of recalculating the constraints which -changed when a ``global-requirements.txt`` change is proposed. In this case, ignore -the changes to ``upper-constraints.txt`` and review the +changed when a ``global-requirements.txt`` change is proposed. In this case, +ignore the changes to ``upper-constraints.txt`` and review the ``global-requirements.txt`` component of the change. stable-branch maintenance diff --git a/doc/source/open-community.rst b/doc/source/open-community.rst index 59d910f..8b5463f 100644 --- a/doc/source/open-community.rst +++ b/doc/source/open-community.rst @@ -151,9 +151,10 @@ of elected technical positions in OpenStack: The *project team* guide naturally focuses on PTLs. More information about the TC can be found on the `Technical Committee website`_. You can reach out to -TC members using the openstack-discuss_ mailing-list (including the ``[tc]`` "tag" -in your subject line will make it more likely for them to see the message), or -on the #openstack-tc IRC channel (especially around `TC office hours`_). +TC members using the openstack-discuss_ mailing-list (including the ``[tc]`` +"tag" in your subject line will make it more likely for them to see the +message), or on the #openstack-tc IRC channel (especially around +`TC office hours`_). Each project team in OpenStack needs a PTL. The PTL is an elected leader who has final say over all things in that specific project team, and all the code diff --git a/doc/source/open-development.rst b/doc/source/open-development.rst index e48f43a..ce13685 100644 --- a/doc/source/open-development.rst +++ b/doc/source/open-development.rst @@ -55,7 +55,8 @@ guides them in the interaction with the contributor. recommend thing to do. Note that these project's guidelines inherit from the OpenStack's guidelines anyway. -#. Verify that the commit message is also compliant with the following criterias: +#. Verify that the commit message is also compliant with the following + criteria: #. The title is not longer than 50 characters. #. Summary lines should be wrapped at 70 characters. @@ -64,11 +65,12 @@ guides them in the interaction with the contributor. Sometimes the patches are partially fixes for a bigger problem and it's extremely important to have all that explicitly stated in the commit message. - #. Make sure the commit message is correctly flagged. If there are API changes - then the `APIImpact` flag should be used. If there are security + #. Make sure the commit message is correctly flagged. If there are API + changes then the `APIImpact` flag should be used. If there are security implications then the `SecurityImpact` flag should be used. If there are documentation changes then the `DocImpact` flag should be used. - #. Make sure blueprints and bugs are correctly referenced in the commit message: + #. Make sure blueprints and bugs are correctly referenced in the commit + message: #. Closes-bug: #12345 #. Implements-blueprint: my-blueprint-slug diff --git a/doc/source/project-setup/javascript.rst b/doc/source/project-setup/javascript.rst index 6445b54..a6b1685 100644 --- a/doc/source/project-setup/javascript.rst +++ b/doc/source/project-setup/javascript.rst @@ -335,8 +335,8 @@ Suggested names patterns: A javascript library of common utilities used in other OpenStack projects, published to bower as :code:`openstack-oslo-jslib` :code:`openstack/ironic-jslib` - A javascript library that integrates with the Ironic API, published to bower - as :code:`openstack-ironic-jslib` + A javascript library that integrates with the Ironic API, published to + bower as :code:`openstack-ironic-jslib` :code:`openstack/ironic-jsclient` A commandline client for ironic, written in JavaScript, published to npm as :code:`openstack-ironic-jsclient` @@ -362,4 +362,4 @@ Example artifact names might include: .. _How to contribute to OpenStack: https://wiki.openstack.org/wiki/How_To_Contribute .. _NPM package scripts: https://docs.npmjs.com/misc/scripts .. _ESLint Project: http://eslint.org -.. _eslint-config-openstack: http://git.openstack.org/cgit/openstack/eslint-config-openstack \ No newline at end of file +.. _eslint-config-openstack: http://git.openstack.org/cgit/openstack/eslint-config-openstack diff --git a/doc/source/ptl.rst b/doc/source/ptl.rst index d59900c..9d7f571 100644 --- a/doc/source/ptl.rst +++ b/doc/source/ptl.rst @@ -136,7 +136,8 @@ At the beginning of a new cycle #. Appoint `cross project liaisons`_ (Docs, release, QA, Oslo, etc.). -#. Appoint `FirstContact SIG liaisons`_ (By default, the liaison will be the PTL). +#. Appoint `First Contact SIG liaisons`_ (By default, the liaison will be the + PTL). #. Check if the meeting time works for most active contributors. @@ -145,7 +146,8 @@ At the beginning of a new cycle #. If necessary, squash database migrations. This is usually not necessary, but will reduce the amount of time necessary for upgrading. A sample - squash can be seen `by the keystone team `_. + squash can be seen `by the keystone + team `_. #. Track removed and deprecated features, for example using `deprecated-as-of-` and `removed-as-of-` blueprints. @@ -170,9 +172,10 @@ During the cycle #. Lack of reviews? Reach out to the core team and remind them. -#. `Release libraries as necessary `_, - but don't wait too long! Some teams will release after 4 weeks even if the changes are - minor. *More often is better than less often.* +#. `Release libraries as + necessary `_, + but don't wait too long! Some teams will release after 4 weeks even if the + changes are minor. *More often is better than less often.* Conference and event tasks ========================== @@ -197,13 +200,14 @@ During the Forum #. In the discussion sessions you moderate: * Take notes on the etherpad (or delegate a scribe) - * Act as a moderator rather than actively participate (or delegate a moderator) + * Act as a moderator rather than actively participate (or delegate a + moderator) -#. After the discussion, post a summary of the session outcome to the ML, for the - benefit of those who could not be present. +#. After the discussion, post a summary of the session outcome to the ML, for + the benefit of those who could not be present. -#. Towards the end of the Forum, ensure a summary of all discussions are sent to the ML for - individuals who did not attend the event. +#. Towards the end of the Forum, ensure a summary of all discussions are sent + to the ML for individuals who did not attend the event. Before the PTG -------------- @@ -215,8 +219,8 @@ Before the PTG #. If your team gathers at the PTG, create an etherpad to dynamically build the room agenda, and list it on the event wiki page. -#. Create a tentative time schedule so that people from other projects who are interested - in a certain topic know when to join in the discussion. +#. Create a tentative time schedule so that people from other projects who are + interested in a certain topic know when to join in the discussion. During the PTG -------------- @@ -226,18 +230,19 @@ During the PTG #. Keep the event schedule up to date on what the current topics of discussion in your team room is. -#. Towards the end of the PTG, ensure a summary of all discussions are sent to the ML for - individuals who did not attend the event. +#. Towards the end of the PTG, ensure a summary of all discussions are sent to + the ML for individuals who did not attend the event. Attending events ---------------- Whilst attending the Summit and PTG as a PTL is preferential, it is not the -end of the world if you are unable to do so for personal or professional reasons. -The community is here to support you, and is available to help plan +end of the world if you are unable to do so for personal or professional +reasons. The community is here to support you, and is available to help plan team orientated events and tasks if you are unable to make the trip. -If you are unable to attend, see our section on `How to successfully delegate`_. +If you are unable to attend, see our section on +`How to successfully delegate`_. At the end of the cycle ======================= @@ -245,8 +250,8 @@ At the end of the cycle #. Clean up release notes. #. Coordinate with the `release management`_ team for deliverables, unless a - liaison has been appointed and make sure release-highlights are documented in - the release files. + liaison has been appointed and make sure release-highlights are documented + in the release files. #. Perform a retrospective via an etherpad. Suggested sections include: `What went well?`, `What didn't go well`. @@ -360,7 +365,8 @@ some community tips on what you can do to help make your experience as an OpenStack project leader better. If you can think of anything else that might be helpful, do not hesitate -to clone the `project-team-guide` repo from `OpenDev `_ +to clone the `project-team-guide` repo from +`OpenDev `_ and submit an addition. - Ensuring your email filters are setup to catch anything with `[ptl]` or @@ -374,94 +380,97 @@ and submit an addition. - Project update emails: An optional extra for when you're getting into the swing of things. Providing an occasional project team update email to the openstack-discuss mailing list is a great way to keep part-time contributors - informed of the changes occurring within the project. For example, the Keystone - team provides updates weekly: http://lists.openstack.org/pipermail/openstack-discuss/2019-June/006799.html + informed of the changes occurring within the project. For example, the + Keystone team provides updates weekly: + http://lists.openstack.org/pipermail/openstack-discuss/2019-June/006799.html -- Set aside time during the weekly meeting to look at the oldest outstanding review - in the project. The resulting action should be one of the following: the patch is - merged, -1'd, or someone is assigned to follow up if the review cannot be completed - in real time. This is a great way to reduce significant backlogs and potential - technical debt. +- Set aside time during the weekly meeting to look at the oldest outstanding + review in the project. The resulting action should be one of the following: + the patch is merged, -1'd, or someone is assigned to follow up if the review + cannot be completed in real time. This is a great way to reduce significant + backlogs and potential technical debt. - Courtesy pings in IRC meetings: Everyone lives busy lives outside of the community. Coming up with a way to ping team members who are interested in attending team meetings is a helpful addition. Another way to do this is to encourage team members to configure their - IRC client to highlight on a specific keyword. For example `#startmeeting ` - or `foo-team`. + IRC client to highlight on a specific keyword. For example + `#startmeeting ` or `foo-team`. -- Manage priority reviews. This can be done by adding a review priority column in Gerrit or - maintaining the priority `blueprint `_ in a spec repo. +- Manage priority reviews. This can be done by adding a review priority column + in Gerrit or maintaining the priority + `blueprint `_ in a spec repo. Here is an example from the Cinder team implemented the review priority column: https://review.opendev.org/#/c/620664/ How to successfully delegate ---------------------------- -Delegating is a large part of your role as an OpenStack PTL. There are numerous tasks -and we know how difficult it can be to keep up with it all. Some projects are more -fortunate than others, having multiple people around to delegate to, however this is -not always the case - no matter the size of the project. +Delegating is a large part of your role as an OpenStack PTL. There are numerous +tasks and we know how difficult it can be to keep up with it all. Some projects +are more fortunate than others, having multiple people around to delegate to, +however this is not always the case - no matter the size of the project. -The following are some tips and tricks derived from community members to help you -delegate: +The following are some tips and tricks derived from community members to help +you delegate: - Reach out to team members on IRC or the mailing lists - everyone communicates differently. -- Detail your ask. Vague requests tend to go ignored because people have their own - workloads. But if you need someone to host a team meeting, summarize the forum or - PTG, or even fix a bug, details are key to getting results. +- Detail your ask. Vague requests tend to go ignored because people have their + own workloads. But if you need someone to host a team meeting, summarize the + forum or PTG, or even fix a bug, details are key to getting results. -- Don't wait until the last minute to ask for help. If you've got a big project on - horizon, find someone to help at the beginning - even if that person is to be your - backup if things fall through. +- Don't wait until the last minute to ask for help. If you've got a big project + on horizon, find someone to help at the beginning - even if that person is to + be your backup if things fall through. If you can't find a delegate, it is okay to let things go. It is not the upmost -importance to have a team meeting, or plan everything perfectly. Here are some tips -to help you deal with being unable to delegate tasks: +importance to have a team meeting, or plan everything perfectly. Here are some +tips to help you deal with being unable to delegate tasks: -- Do not be afraid to reach out to other project teams, the TC, or the UC for help. - The TC and the UC are designed to provide guidance and support where possible. +- Do not be afraid to reach out to other project teams, the TC, or the UC for + help. The TC and the UC are designed to provide guidance and support where + possible. -- Don't be a hero. Ensure people are aware that you are having troubles and some deliverables - might not be met. We care about our community members, and it's important that you feel - supported, and not crushed. +- Don't be a hero. Ensure people are aware that you are having troubles and + some deliverables might not be met. We care about our community members, and + it's important that you feel supported, and not crushed. Handing over PTL duties ======================= -Are you thinking of moving on? Hoping to encouraging healthy rotation in the role? -Perhaps you've decided you've had enough and you're burnt out. Or perhaps you're -moving to a new role or company and OpenStack is no longer your work priority. -There are a myriad of reasons why someone would need or want to move on from -the PTL position. While the community would be sad to see you step down, it is -part of the lifecycle of the position and it's often a positive change to see new -people and new ideas into leadership positions. +Are you thinking of moving on? Hoping to encouraging healthy rotation in the +role? Perhaps you've decided you've had enough and you're burnt out. Or perhaps +you're moving to a new role or company and OpenStack is no longer your work +priority. There are a myriad of reasons why someone would need or want to move +on from the PTL position. While the community would be sad to see you step +down, it is part of the lifecycle of the position and it's often a positive +change to see new people and new ideas into leadership positions. -Handing over the PTL position is not easy, it's not as simple as pinging someone -who is an active contributor and asking if they're interested or not. The main thing -is to get the individual up to speed on the content covered in this document, as it -may be things they have not encountered yet. +Handing over the PTL position is not easy, it's not as simple as pinging +someone who is an active contributor and asking if they're interested or not. +The main thing is to get the individual up to speed on the content covered in +this document, as it may be things they have not encountered yet. .. note:: - There are some important bits of information to pass on, but you're never going - to have a complete knowledge transfer. This is okay! + There are some important bits of information to pass on, but you're never + going to have a complete knowledge transfer. This is okay! -To make that process a little bit easier for you, and for them, offer PTL mentoring -before stepping down. If you know that your situation is going to change in advance, -why not reach out to the whole team and ask who is interested and if you could mentor -them in the last few months? +To make that process a little bit easier for you, and for them, offer PTL +mentoring before stepping down. If you know that your situation is going to +change in advance, why not reach out to the whole team and ask who is +interested and if you could mentor them in the last few months? -If there are no takers, reach out to the OpenStack TC before stepping down so they -are aware of the current situation and can step in to help. +If there are no takers, reach out to the OpenStack TC before stepping down so +they are aware of the current situation and can step in to help. .. _meetings: http://docs.openstack.org/project-team-guide/cross-project.html#meetings .. _release calendar: https://releases.openstack.org/schedule.ics .. _cross project liaisons: https://wiki.openstack.org/wiki/CrossProjectLiaisons .. _release management: http://docs.openstack.org/project-team-guide/release-management.html -.. _FirstContact SIG liaisons: https://wiki.openstack.org/wiki/First_Contact_SIG#Project_Liaisons +.. _First Contact SIG liaisons: https://wiki.openstack.org/wiki/First_Contact_SIG#Project_Liaisons .. _weekly meetings: http://eavesdrop.openstack.org/#User_Committee_Meeting .. _openstack-discuss: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss diff --git a/doc/source/release-management.rst b/doc/source/release-management.rst index 8c676c1..9deed20 100644 --- a/doc/source/release-management.rst +++ b/doc/source/release-management.rst @@ -741,9 +741,9 @@ You can check on the formatting of the output by either running locally: tox -e docs -And checking the resulting file under ``doc/build/html/$RELEASE/highlights.html``, -or you can view the output of the ``build-openstack-sphinx-docs`` job under -``html/$RELEASE/highlights.html``. +And checking the resulting file under +``doc/build/html/$RELEASE/highlights.html``, or you can view the output of the +``build-openstack-sphinx-docs`` job under ``html/$RELEASE/highlights.html``. Writing a Good Cycle Highlight ------------------------------ diff --git a/doc/source/stable-branches.rst b/doc/source/stable-branches.rst index 524cdd6..ef47cc6 100644 --- a/doc/source/stable-branches.rst +++ b/doc/source/stable-branches.rst @@ -44,9 +44,9 @@ in the Maintained phase while all other projects have transitioned to either `Extended Maintenance`_ or even `End of Life`_. .. note:: - At this time the exact mechanism for describing and updating this state is undefined - but it's probable it will involved updating a meta-data in a projects - deliverable file in the :code:`openstack/releases` repo. + At this time the exact mechanism for describing and updating this state is + undefined but it's probable it will involved updating a meta-data in a + projects deliverable file in the :code:`openstack/releases` repo. .. _Maintained: @@ -72,8 +72,8 @@ releases and `OpenStack Vulnerability Management`_ will be reasonable efforts only. There is no statement about the level of testing and upgrades from Extended Maintenance are not supported within the Community. -The ``last release`` of the appropriate branch will be tagged as ``$series-em``, -for example: https://review.opendev.org/608296/. +The ``last release`` of the appropriate branch will be tagged as +``$series-em``, for example: https://review.opendev.org/608296/. For all projects that follow the stable policy a patch with a ``$series-em`` tag will be automatically generated after the final release from the latest development cycle happened. This is because this is a less busy period in @@ -98,10 +98,11 @@ of Life`_ below. Unmaintained ------------ -At this stage of the project/branch the Extended Maintenance policy applies but CI -may not be working and/or there aren't any active maintainers. Projects that -remain in this state for 6 months will be transitioned to `End of Life`_. -Should maintainers be found a project can be placed back into Extended Maintenance. +At this stage of the project/branch the Extended Maintenance policy applies but +CI may not be working and/or there aren't any active maintainers. Projects +that remain in this state for 6 months will be transitioned to `End of Life`_. +Should maintainers be found a project can be placed back into Extended +Maintenance. .. _End Of Life: @@ -214,20 +215,20 @@ branches which generally includes: appropriate branches quickly. #. Monitoring the backlog of open backport reviews and actually reviewing them in a timely manner. -#. Releasing frequently enough to get fixes out without overwhelming the release - team or consumers. In general, security fixes and other critical bug fixes - should be released quickly. Otherwise when there are a reasonable amount of - unreleased fixes committed, teams should be looking at doing a release. - Milestone boundaries during the master release schedule are also good times - to be inspecting the list of unreleased changes to see if a stable point - release should happen. +#. Releasing frequently enough to get fixes out without overwhelming the + release team or consumers. In general, security fixes and other critical bug + fixes should be released quickly. Otherwise when there are a reasonable + amount of unreleased fixes committed, teams should be looking at doing a + release. Milestone boundaries during the master release schedule are also + good times to be inspecting the list of unreleased changes to see if a + stable point release should happen. #. Monitoring and resolving issues in the continuous integration 'gate' system. This basically means making sure there aren't things blocking proposed backports from passing tests. These could be project-specific or global in nature and are usually tracked in the `stable tracker etherpad`_. From time to time the Stable Maintenance Core team may also ask for help from - individual projects in IRC or the openstack-discuss mailing list and expect a - reasonably prompt response. + individual projects in IRC or the openstack-discuss mailing list and expect + a reasonably prompt response. .. note:: Projects with the ``stable:follows-policy`` tag should be running the @@ -304,7 +305,8 @@ Backport examples: * A change for Tango must exist in :code:`master` * A change for Sierra must exist in :code:`stable/tango` and :code:`master` -* A change for Romeo must exist in :code:`stable/sierra`, :code:`stable/tango` and :code:`master` +* A change for Romeo must exist in :code:`stable/sierra`, :code:`stable/tango` + and :code:`master` * and so on Proposing Fixes @@ -320,11 +322,11 @@ If you don't have the appropriate permissions to nominate the bug, then tagging it with e.g. *$release-backport-potential* is also sufficient e.g. `Nova Liberty potential`_ -The best way to get the patch merged in a timely manner is to send it backported -by yourself. To do so, you may try to use the "Cherry Pick To" button in the -Gerrit UI for the original patch in master. Gerrit will take care of creating a -new review, modifying the commit message to include 'cherry-picked from ...' -line etc. +The best way to get the patch merged in a timely manner is to send it +backported by yourself. To do so, you may try to use the "Cherry Pick To" +button in the Gerrit UI for the original patch in master. Gerrit will take care +of creating a new review, modifying the commit message to include +'cherry-picked from ...' line etc. .. note:: The backport must match the master commit, unless there is a serious need to @@ -373,10 +375,10 @@ Email Notifications If you want to be notified of new stable patches you can create a watch on the gerrit `watched projects`_ screen with the following settings. -.. code-block:: none +.. code-block:: - Project Name: All-Projects - Only If: branch:stable/liberty + Project Name: All-Projects + Only If: branch:stable/liberty Then check the "Email Notifications - New Changes" checkbox. That will cause gerrit to send an email whenever a matching change is proposed, and better yet, diff --git a/tox.ini b/tox.ini index e9ee42b..a9a587b 100644 --- a/tox.ini +++ b/tox.ini @@ -16,4 +16,10 @@ commands = {posargs} [testenv:docs] basepython = python3 deps = -r{toxinidir}/doc/requirements.txt -commands = sphinx-build -W -b html doc/source doc/build/html +commands = + doc8 + sphinx-build -W -b html doc/source doc/build/html + +[doc8] +ignore-path=.tox,doc/build,.eggs/,./*.txt,project_team_guide.egg-info/ +extensions=.txt,.rst,.inc