wiki:CodingGuidelines/SubmittingPatches

Submitting Patches

Expressing your desire to work on a ticket

By default, tickets are assigned to a default component owner. If you wish to work on an assigned ticket, simply comment on the ticket to inform the person. For the most part, this is to reduce the frustration of duplicating work.

Coding style

The Coding Guidelines are expected to be followed when submitting patches.

Note: When patching existing files that do not follow our Coding Guidelines, it is preferable to apply the stylization to the entire file. If that is not possible, then conform to the pervading style being used.

Be aware, that these style checker tools may generate false positives (eg, evaluating comments as coding violations) or may miss other violations.

Automatic white space cleanup

Sometimes you'll see a commit message of "Automatic white space cleanup. No functional change.", for example hrev36509. It is preferred for new code to not introduced unneeded white space. Luckily, there is an option in Pe to perform this for you automatically. Here is how to enable it from within Pe.

  • In the menu bar, select Window --> Preferences
  • Select "Files" from the left pane
  • enable [x] Discard trailing space
  • click [Apply]

Now, when you save & close a file, any stray spaces at the end of any lines will be automatically removed.

Committing changes

  • Before making any commits to the Haiku repository (local even), be sure to configure the git environment on your local system! Failure to configure git properly before a commit will result in incorrect naming in your commit.
  • git status will display which files are modified, added, or deleted. Use git diffto inspect your changes.
  • You'll then have to commit your changes locally by adding the changed or added files (git add my-file my/new/file), and then do a git commit.
    • You will need to enter a complete commit message that will later appear as is in Haiku's repository if your patch is going to be accepted.
    • The first line of the message is the title that should be as descriptive as possible while not exceeding 50 characters.
    • After an empty line you should add a detailed description what you're trying to fix and how.
    • If you solve a ticket in the bugtracker with it, add a "Fixes #{ticketnumber}." at the end, on its own line.

Submitting your commit(s)

Create an account on Haiku's Gerrit instance using your GitHub account, and add your SSH keys.

Note: Any commits submitted to Gerrit must have the same email address and user name as is in your Gerrit account, or else Gerrit will reject your submission!

Then submit your commits to Gerrit like this:

git push origin <local source branch>:refs/for/<remote target branch>

Most likely, you are submitting from your local master branch to the remote master branch, in which case you would use:

git push origin master:refs/for/master

After pushing, either create a new ticket about this patch or comment on the ticket your patch fixes with a link to the Gerrit review.

Updating your commit(s)

If you need to make changes to your code in the course of a review at Haiku's Gerrit, you make them locally and amend them to your submitted commit:

git commit -a --amend

Make sure to add "Change-Id: here-goes-the-ID-of-your-gerrit-ticket" at the end of the commit message. Otherwise you'll create a new gerrit ticket!

You submit that update in the same way as you did the original commit:

git push origin <local source branch>:refs/for/<remote target branch>

Following up

Lastly and most importantly: once a developer reviews your submitted code, expect them to point out any and all flaws. This is standard procedure and is constructive criticism. Remember, we want to help you improve your coding abilities.

You may want to either subscribe to or read the haiku-commits mailing list archives. It happens that discussions of recently committed code occur on this list, even if normally the discussion is mainly on our Gerrit instance...

Last modified 7 weeks ago Last modified on Sep 4, 2018 3:47:36 PM