From ed13b8a6846ffc9160b7175c1015d44c97a683d3 Mon Sep 17 00:00:00 2001 From: "Jay S. Bryant" Date: Thu, 17 May 2018 12:37:27 -0500 Subject: [PATCH] Fix some wording and typos This patch just fixes some wording issues and typos in the patch-best-practices.rst file. Change-Id: I1c5d056646e82e888c70514bc5bca9a90c337340 --- .../patch-best-practices.rst | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/source/code-and-documentation/patch-best-practices.rst b/doc/source/code-and-documentation/patch-best-practices.rst index 94c129f..9eff3ec 100644 --- a/doc/source/code-and-documentation/patch-best-practices.rst +++ b/doc/source/code-and-documentation/patch-best-practices.rst @@ -16,14 +16,14 @@ Reviewing large patches is very inconvenient and time consuming therefore we 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 -as possible**, but under a few hunderds of line changes total. Patches that are -test heavy with little code change require as much effort as code heavy +as possible**, but under a few hundreds of lines changed total. Patches that +are test heavy with little code change require as much effort as code heavy changes. 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 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 or logical parts of the functionality that do not depend on common functions @@ -53,8 +53,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 between the dependencies of your changes. -The 'Depends-On' tag is only a marker on your changes and in case you apply it -a patch cannot be merged until all its dependencies got landed. +The 'Depends-On' tag is a marker on your changes and when used +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 that case the changes are separate enough to be kept indenependent which means @@ -64,7 +64,7 @@ patch basis. It is also true for rebasing each patch. .. note:: 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 of handling the dependencies automatically in this case. @@ -82,9 +82,9 @@ related tests in one patch as you cannot guarantee that both land in time for a release. 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 -also links which help you navigate between the changes to review them when you -upload a new version. +'Related Changes' column on the top right corner of the Gerrit UI. The titles +are also links which help you navigate between the changes to review them when +you upload a new version. How to Handle Chains? --------------------- @@ -130,10 +130,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 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 -also show them to you in the 'Same Topic' column on the upright corner of the -page of a review. +also show them to you in the 'Same Topic' column on the top right corner of +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. How to Structure Your Changes? @@ -169,7 +169,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. 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 related to fix that are less welcomed and are sources of very opinionated arguments that should be avoided.