How to work on a bug¶
Any defect, even minor, if it changes the user-visible server behavior, needs a bug report. Report a bug at http://github.com/tarantool/tarantool/issues.
When reporting a bug, try to come up with a test case right away. Set the current maintenance milestone for the bug fix, and specify the series. Assign the bug to yourself. Put the status to ‘In progress’ Once the patch is ready, put the bug the bug to ‘In review’ and solicit a review for the fix.
Once there is a positive code review, push the patch and set the status to ‘Closed’
Patches for bugs should contain a reference to the respective Launchpad bug page or at least bug id. Each patch should have a test, unless coming up with one is difficult in the current framework, in which case QA should be alerted.
There are two things you need to do when your patch makes it into the master:
- put the bug to ‘fix committed’,
- delete the remote branch.
How to write a commit message¶
Any commit needs a helpful message. Mind the following guidelines when committing to any of Tarantool repositories at GitHub.
- Separate subject from body with a blank line.
- Try to limit the subject line to 50 characters or so.
- Start the subject line with a capital letter unless it prefixed with a
subsystem name and semicolon:
- Do not end the subject line with a period.
- Do not put “gh-xx”, “closes #xxx” to the subject line.
- Use the imperative mood in the subject line. A properly formed Git commit subject line should always be able to complete the following sentence: “If applied, this commit will /your subject line here/”.
- Wrap the body to 72 characters or so.
- Use the body to explain what and why vs. how.
- Link GitHub issues on the lasts lines (see how).
- Use your real name and real email address. For Tarantool team members, @tarantool.org email is preferred, but not mandatory.
Summarize changes in 50 characters or less More detailed explanatory text, if necessary. Wrap it to 72 characters or so. In some contexts, the first line is treated as the subject of the commit, and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like `log`, `shortlog` and `rebase` can get confused if you run the two together. Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that). Are there side effects or other unintuitive consequences of this change? Here's the place to explain them. Further paragraphs come after blank lines. - Bullet points are okay, too. - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here. Fixes: #123 Closes: #456 Needed for: #859 See also: #343, #789
Some real-world examples:
How to submit a patch for review¶
Since 24.01.2018 changes prepared for review should be submitted to firstname.lastname@example.org.
e-mail messages are prepared using
git format-patch and
What a mail thread is and why is it useful?
An email thread keeps the review history local: all iterations are stored in a single mail thread, thus making navigation simple.
When a cover letter is needed?
A cover letter unifies multiple patches (a patchset) into a single thread.
So, a cover letter is needed at all times, unless a patchset contains just one patch. If so, it’s the commit message that plays the cover letter’s role.
What to put in a cover letter?
A cover letter must contain:
If the patchset contains just one patch, all this information is present within the patch:
Which options to add to
The required options are:
What prefixes to put in the subject?
How to refer to the git branch and issue (in a cover letter)?
How to put updated changes derived from rebasing (force-pushing) into the same mail thread?
Check here for scripts which might be useful for preparing e-mail messages.