Development/gerrit/SubmitPatch/pt-br
TDF LibreOffice Brasil Document Liberation Project Community Blogs Traduções Nextcloud Redmine Perguntas e respostas Doar
Submit a patch for review with gerrit
Submitting patches for review
Stephan Bergmann gave a helpful presentation in FOSDEM 2021 called The Perfect Gerrit Patch - a consumer report.
Important: there is normally never a reason to abandon your patch. Please read carefully the section about submitting a new version.
Create and push your change to gerrit for review (official gerrit documentation is here):
git checkout -b <span lang="en" dir="ltr" class="mw-content-ltr"><a_local_branch_name_of_your_choice></span> origin/master
# <span lang="en" dir="ltr" class="mw-content-ltr">Do your code changes, make sure it will build</span>
git add file1 <span lang="en" dir="ltr" class="mw-content-ltr">[file2 ...] # all the new files _and_ changed files</span>
git commit
./logerrit submit masterNote: for the `logerrit` command to work, make sure you have set yourself up for gerrit. Instructions can be found here.
The first command creates a new branch, and makes it track origin/master remote branch. This allows following ./g pull -r to rebase your branch automatically on the latest master, which may be a necessary precondition to submit, when your branch gets older than a week.
If you had created a branch without specifying a remote branch to track, and now ./g pull -r doesn't rebase the branch automatically, you may also use command git branch -u origin/master on an existing branch to start tracking.
Note: the git add + git commit step can be done using 'git gui', please remember that the commit subject line should not be longer than 72 characters and the commit message lines, if any, should not be longer than 80 characters.
Note: for submissions to master, it is useful to (re)base the changes on a recent version of master, so that CI builds on jenkins can benefit as much as possible from ccache.
Note: LibreOffice uses clang-format to check the patches for conformance to established rules. We use a specific version of clang-format (to avoid inconsistencies that exist between different versions of it, even between minor releases). If there's no clang-format preinstalled on system, a warning will be issued at the time of git commit, with instructions on how to install the required binaries.
If you have some version preinstalled, you might not see warnings (but have inconsistent results when buildbots would fail telling you to change formatting the other way), or the preinstalled version might not work (e.g., complaining about command line options). The version used by LibreOffice may be found at https://dev-www.libreoffice.org/bin/.
Only the last line is special and will push all patches in the named local branch to the review queue for the master branch (Adjust accordingly, if you want to submit a patch to one of the release branches or other branches). As a casual contributor your patch needs to have the same email address as your gerrit account has or you will not be allowed to push.
If the push succeeds, git will report where your commit is waiting for review. The url will look something like https://gerrit.libreoffice.org/#/c/229/.
It is a good idea to keep your local branch around while your patch is under review, that will allow to possibly easily push a new version of the patch. In the mean time you can
git checkout masterTo return to the master branch... and you can start working on another patch using again the procedure above (create local branch, code, commit, push to gerrit).
Add yourself to the contributor list
If this is the first time you are contributing a patch to the LibreOffice project, please add yourself to the developer and contributor list (following the instructions there) and state the license of your contributions.
Please only send the statement no earlier than when you post your first submission to gerrit and ensure you have permission from your parents!
Alternative: use git review
As an alternative to the above, you can consider using "git review", as explained at Development/GitReview.
Reviewing patches
The next step after submitting a patch is collaboratively reviewing it on gerrit. See Development/gerrit/PatchReview to learn more.
Detailed discussion on some patch submission topics
Submitting a new version
If during the review of one of your patch you need to submit a new version of it, then do:
git checkout <div lang="en" dir="ltr" class="mw-content-ltr">
<local_branch_associated_with_your_patch>
<do your modification>
</div>
git add ...
git commit --amend # <span lang="en" dir="ltr" class="mw-content-ltr">Modifies the last commit on the branch rather than creating a new one. Never use the -m option here!</span>
./logerrit submit masterNote that gerrit will detect that it is a new version of an existing change (thanks to the Change-Id line automatically inserted into the commit message when it was originally submitted).
 |
Tip:
|
Using git review to amend changes and submit new patch versions
Amending changes manually in the above way can quickly get confusing and keeping track of local_branch_associated_with_your_patch is error prone (associated how anyway?). If you submitted several changes to gerrit then keeping them all on the master branch and amending them independently is impossible. You will either have to reset HEAD^ after each submission and download/modify/amend/submit/reset for each new patch set, or do that in separate branches and this is where git review comes in handy.
Please read Development/GitReview#Amending_a_gerrit_change for how to do that.
Submitting patches as private or work-in-progress
If you use ./logerrit submit master%private instead of ./logerrit submit master, you will create a private change.
Such a change will only be visible to yourself and whoever you add as a reviewer with the 'add reviewer' button in gerrit.
If you don't need to hide your change from the general public, you can use ./logerrit submit master%wip to create a work-in-progress change.
If you are not using logerrit, push to refs/for/branch%private or refs/for/branch%wip.
You can also toggle the private and WIP states from the gerrit UI.
Submit patches for review from dictionaries, helpcontent2, translations submodules
See the page dedicated to Submodules.
Cherry picking yourself out of trouble
Ignoring the advice about submitting new versions of patches is common. This might lead to deleting a local branch or submitting a new patch depending on an older patch. In order to work on your original patch locally again, do the following:
- In a terminal, check out a new branch from master
- Click the kebab menu in the top right corner of the Gerrit patch view
- Select Download patch
- Click the copy button next to Cherry Pick
- Paste the copied command into your terminal
- Follow the modifying and amending advice from the section about submitting a new version