openstack
/
contributor-guide
Code Issues Proposed changes

Merge "Fix some wording and typos"

This commit is contained in:
Zuul 2018-05-17 23:21:08 +00:00 committed by Gerrit Code Review
parent 13842c3263 ed13b8a684
commit e77e1e8158
1 changed files with 13 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/source/code-and-documentation/patch-best-practices.rst
View File

@ -22,14 +22,14 @@ Reviewing large patches is very inconvenient and time consuming therefore we
always suggest to break down your changes into smaller blocks. always suggest to break down your changes into smaller blocks.
While there is no magic number try to **keep the size of your changes as small While there is no magic number try to **keep the size of your changes as small
as possible**, but under a few hunderds of line changes total. Patches that are as possible**, but under a few hundreds of lines changed total. Patches that
test heavy with little code change require as much effort as code heavy are test heavy with little code change require as much effort as code heavy
changes. changes.
In rare occasions when there is no good logical breakdown for a change and your In rare occasions when there is no good logical breakdown for a change and your
patch can grow to a thousand lines or more. In some cases it is acceptable as patch can grow to a thousand lines or more. In some cases it is acceptable as
you cannot extract the related test changes to another patch for instance, but you cannot extract the related test changes to another patch for instance, but
it's highly not highly recommended. it's not highly recommended.
Always try to extract as much as you can into other patches, like documentation Always try to extract as much as you can into other patches, like documentation
or logical parts of the functionality that do not depend on common functions or logical parts of the functionality that do not depend on common functions
@ -59,8 +59,8 @@ patches with the 'Depends-On' tag. The tag will appear as a link in the
commit message which helps you and also the reviewers to track and navigate commit message which helps you and also the reviewers to track and navigate
between the dependencies of your changes. between the dependencies of your changes.
The 'Depends-On' tag is only a marker on your changes and in case you apply it The 'Depends-On' tag is a marker on your changes and when used
a patch cannot be merged until all its dependencies got landed. a patch cannot be merged until all its dependencies are landed.
The tag can be applied to patches proposed for the same repository as well. In The tag can be applied to patches proposed for the same repository as well. In
that case the changes are separate enough to be kept indenependent which means that case the changes are separate enough to be kept indenependent which means
@ -70,7 +70,7 @@ patch basis. It is also true for rebasing each patch.
.. note:: .. note::
In case you use the 'Depends-On' tag you need to download all the changes In case you use the 'Depends-On' tag you need to download all the changes
for a feature implementation or documentation work to test the feature or for a feature implementation or documentation change to test the feature or
build the documentation with all the changes applied. Git will not take care build the documentation with all the changes applied. Git will not take care
of handling the dependencies automatically in this case. of handling the dependencies automatically in this case.
@ -88,9 +88,9 @@ related tests in one patch as you cannot guarantee that both land in time for a
release. release.
When you have a chain Gerrit helps you by listing all the commit titles in the When you have a chain Gerrit helps you by listing all the commit titles in the
'Related Changes' column on the upright corner of the Gerrit UI. The titles are 'Related Changes' column on the top right corner of the Gerrit UI. The titles
also links which help you navigate between the changes to review them when you are also links which help you navigate between the changes to review them when
upload a new version. you upload a new version.
How to Handle Chains? How to Handle Chains?
--------------------- ---------------------
@ -136,10 +136,10 @@ You have the option to specify a topic for your changes when you upload them
for review. While Gerrit topics will not add dependency to your patches you can for review. While Gerrit topics will not add dependency to your patches you can
apply a search based on the topic that will show you all the relevant changes apply a search based on the topic that will show you all the relevant changes
in all the projects where there are patches with the same topic. Gerrit will in all the projects where there are patches with the same topic. Gerrit will
also show them to you in the 'Same Topic' column on the upright corner of the also show them to you in the 'Same Topic' column on the top right corner of
page of a review. the page of a review.
This is a good way to help tracking related changes let that be a feature This is a good way to help tracking related changes, let that be a feature
implementation, bugfix or documentation work. implementation, bugfix or documentation work.
How to Structure Your Changes? How to Structure Your Changes?
@ -175,7 +175,7 @@ do it for a larger block, like a whole guide. It is also preferred to report a
story with tasks for a work item like this that can be tracked later. story with tasks for a work item like this that can be tracked later.
It is similar for code improvements. As the community is large and world-wide It is similar for code improvements. As the community is large and world-wide
we have coding guidelines, but the style of each individuals can still be very we have coding guidelines, but the style of each individual can still be very
different. We don't enforce a particular coding style, therefore changes different. We don't enforce a particular coding style, therefore changes
related to fix that are less welcomed and are sources of very opinionated related to fix that are less welcomed and are sources of very opinionated
arguments that should be avoided. arguments that should be avoided.