Enable linting

Enable linting with doc8 and fix all problems found so that it passes.

Change-Id: I052a1b8d016ae396917ae06c22ec29062aa10a2a
This commit is contained in:
Andreas Jaeger 2018-11-14 17:23:22 +01:00
parent 63d7a30840
commit 30ef8472fa
5 changed files with 29 additions and 18 deletions

View File

@ -3,6 +3,8 @@
- build-openstack-docs-pti - build-openstack-docs-pti
check: check:
jobs: jobs:
- tox-linters: - tox-linters
voting: false gate:
jobs:
- tox-linters

View File

@ -6,7 +6,8 @@ Where do the Four Opens originate from? They came from a need to do things
differently. differently.
Free software started in the 80s by defining four (initially three) Free software started in the 80s by defining four (initially three)
freedoms [#fourfreedoms]_ that any free software should grant its users. Freedom freedoms [#fourfreedoms]_ that any free software should grant its
users. Freedom
0 was the freedom to run the program as you wish, for any purpose. Freedom 1 0 was the freedom to run the program as you wish, for any purpose. Freedom 1
was the freedom to study how the program works, and change it so it does your was the freedom to study how the program works, and change it so it does your
computing as you wish. Freedom 2 was the freedom to redistribute copies so you computing as you wish. Freedom 2 was the freedom to redistribute copies so you
@ -25,7 +26,7 @@ by 2010 most open source projects were actually closed one way or another:
their core development may be done behind closed walls, or their governance may their core development may be done behind closed walls, or their governance may
be locked down to ensure control by its main sponsor. Sure, their end product be locked down to ensure control by its main sponsor. Sure, their end product
was licensed under an open source license, but those were not really community was licensed under an open source license, but those were not really community
projects anymore. projects anymore.
The control of a specific party over the code is discouraging contributors to The control of a specific party over the code is discouraging contributors to
participate: those are seen as free labor and are not on a level playing field participate: those are seen as free labor and are not on a level playing field

View File

@ -26,15 +26,21 @@ and downstream, but communities are complex organisms, and the reality is much
more dynamic. It's important to establish common goals and build strong more dynamic. It's important to establish common goals and build strong
connections between the forces, because operating in silos will dilute the connections between the forces, because operating in silos will dilute the
power of the community. Each force affects the others and they have to be power of the community. Each force affects the others and they have to be
working in harmony to achieve anything. working in harmony to achieve anything.
Open Community defines how to best align these forces through: Open Community defines how to best align these forces through:
- Common mission & goals. - Effective governance & leadership. - Diversity & - Common mission & goals.
Inclusiveness. - Contributor recognition & motivation. - Communication. - - Effective governance & leadership.
Branding & positioning (example of collaboration across forces, product - Diversity & Inclusiveness.
definition). - Education & On-boarding. - Marketing & events. - Ambassadors - Contributor recognition & motivation.
& meet-ups. - Cross-community collaboration (NIH). - Communication.
- Branding & positioning (example of collaboration across forces, product
definition).
- Education & On-boarding.
- Marketing & events.
- Ambassadors & meet-ups.
- Cross-community collaboration (NIH).
Common Mission & Goals Common Mission & Goals
---------------------- ----------------------
@ -200,10 +206,10 @@ ultimately realized that we excluded a large portion of the world where Google
products were inaccessible/unavailable. products were inaccessible/unavailable.
Host meetings in way that can be archived and searched so that the Host meetings in way that can be archived and searched so that the
conversations are accessible to all time-zones and participants who do not speak conversations are accessible to all time-zones and participants who do
English as their first language. Internationalization (translation, tool not speak English as their first language. Internationalization
choices like google docs, time-zones), in general, helps foster a more diverse (translation, tool choices like google docs, time-zones), in general,
group of contributors. helps foster a more diverse group of contributors.
Board meetings in particular should be open so that anyone can dial in. Board meetings in particular should be open so that anyone can dial in.
Notes/re-cap should be sent out to the community at large via mailing lists Notes/re-cap should be sent out to the community at large via mailing lists

View File

@ -24,7 +24,8 @@ evaluating a patch can include:
not introduce regressions? not introduce regressions?
- Documentation: does a new feature include documentation on what - Documentation: does a new feature include documentation on what
it does and how to properly configure it? it does and how to properly configure it?
- Purpose: does the code implement a feature identified in the open design process? - Purpose: does the code implement a feature identified in the open
design process?
Automation, like automated unit, integration, and style checking, can go a long Automation, like automated unit, integration, and style checking, can go a long
way to establishing a baseline standard for new code. Code review by trusted way to establishing a baseline standard for new code. Code review by trusted

View File

@ -52,12 +52,13 @@ The "Open Source" Principle in Practice
"Open Source" begins with the choice of license a community applies to its "Open Source" begins with the choice of license a community applies to its
project. In most cases at the OpenStack Foundation, we use v2.0 of the Apache project. In most cases at the OpenStack Foundation, we use v2.0 of the Apache
License [#apachev2]_. The license meets the requirements of being able to modify and License [#apachev2]_. The license meets the requirements of being able
to modify and
redistribute a work. It includes a number of provisions that also protect redistribute a work. It includes a number of provisions that also protect
end-users by granting copyright and patent licenses to all end users, while end-users by granting copyright and patent licenses to all end users, while
limiting liability to the original copyright holder. This patent protection is limiting liability to the original copyright holder. This patent protection is
one of the distinguishing features in comparison to other open source licenses, one of the distinguishing features in comparison to other open source licenses,
like the MIT License. like the MIT License.
In practice, individual and corporate contributors need to understand the In practice, individual and corporate contributors need to understand the
consequences of contributing code to an Apache Licensed project, particularly consequences of contributing code to an Apache Licensed project, particularly
@ -73,7 +74,7 @@ authorized to submit changes to the project and understands that their
contributions will be used in accordance with the license. A CLA, being a contributions will be used in accordance with the license. A CLA, being a
stronger document, is also considered a barrier to entry. A DCO, in contrast, stronger document, is also considered a barrier to entry. A DCO, in contrast,
lowers the barrier to entry by removing the requirement to consent to a legal lowers the barrier to entry by removing the requirement to consent to a legal
document [#CLAvDCO]_. document [#CLAvDCO]_.
Apache 2.0 is very liberal in allowing companies to modify and use the code in Apache 2.0 is very liberal in allowing companies to modify and use the code in
any way they want, and doesn't place requirements to release changes (although any way they want, and doesn't place requirements to release changes (although