This adds the Contributing Tutorial (contributing-tutorial.md) to the pages setting of Mkdocs, so that the tutorial will render in the readthedocs.io documentation. Closes: #1711 Approved by: jlebon
5.3 KiB
Submitting patches
A majority of current maintainers prefer the GitHub pull request model, and this motivated moving the primary git repository to https://github.com/ostreedev/ostree.
However, we do not use the "Merge pull request" button, because we do
not like merge commits for one-patch pull requests, among other
reasons. See this issue
for more information. Instead, we use an instance of
Homu, currently known as
cgwalters-bot
.
As a review proceeds, the preferred method is to push fixup!
commits. Any commits committed with the --fixup
option will have have the word fixup!
in its commit title. This is to indicate that this particular commit will be squashed with the commit that was specified in this command, git commit --fixup <commit ref or hash>
. Homu knows how to use --autosquash
when performing the final merge.
See the Git documentation for more information.
Alternative methods if you don't like GitHub (also fully supported):
- Send mail to ostree-list@gnome.org, with the patch attached
- Attach them to https://bugzilla.gnome.org/
It is likely however once a patch is ready to apply a maintainer will push it to a GitHub PR, and merge via Homu.
Commit message style
Please look at git log
and match the commit log style, which is very
similar to the
Linux kernel.
You may use Signed-off-by
, but we're not requiring it.
General Commit Message Guidelines:
- Title
- Specify the context or category of the changes e.g.
lib
for library changes,docs
for document changes,bin/<command-name>
for command changes, etc. - Begin the title with the first letter of the first word capitalized.
- Aim for less than 50 characters, otherwise 72 characters max.
- Do not end the title with a period.
- Use an imperative tone.
- Specify the context or category of the changes e.g.
- Body
- Separate the body with a blank line after the title.
- Begin a paragraph with the first letter of the first word capitalized.
- Each paragraph should be formatted within 72 characters.
- Content should be about what was changed and why this change was made.
- If your commit fixes an issue, the commit message should end with
Closes: #<number>
.
Commit Message example:
<context>: Less than 50 characters for subject title
A paragraph of the body should be within 72 characters.
This paragraph is also less than 72 characters.
For more information see How to Write a Git Commit Message
Editing a Committed Message:
To edit the message from the most recent commit run git commit --amend
. To change older commits on the branch use git rebase -i
. For a successful rebase have the branch track upstream master
. Once the changes have been made and saved, run git push --force origin <branch-name>
.
Running the test suite
OSTree uses both make check
and supports the
Installed Tests
model as well (if --enable-installed-tests
is provided).
Coding style
Indentation is GNU. Files should start with the appropriate mode lines.
Use GCC __attribute__((cleanup))
wherever possible. If interacting
with a third party library, try defining local cleanup macros.
Use GError and GCancellable where appropriate.
Prefer returning gboolean
to signal success/failure, and have output
values as parameters.
Prefer linear control flow inside functions (aside from standard
loops). In other words, avoid "early exits" or use of goto
besides
goto out;
.
This is an example of an "early exit":
static gboolean
myfunc (...)
{
gboolean ret = FALSE;
/* some code */
/* some more code */
if (condition)
return FALSE;
/* some more code */
ret = TRUE;
out:
return ret;
}
If you must shortcut, use:
if (condition)
{
ret = TRUE;
goto out;
}
A consequence of this restriction is that you are encouraged to avoid deep nesting of loops or conditionals. Create internal static helper functions, particularly inside loops. For example, rather than:
while (condition)
{
/* some code */
if (condition)
{
for (i = 0; i < somevalue; i++)
{
if (condition)
{
/* deeply nested code */
}
/* more nested code */
}
}
}
Instead do this:
static gboolean
helperfunc (..., GError **error)
{
if (condition)
{
/* deeply nested code */
}
/* more nested code */
return ret;
}
while (condition)
{
/* some code */
if (!condition)
continue;
for (i = 0; i < somevalue; i++)
{
if (!helperfunc (..., i, error))
goto out;
}
}
Contributing Tutorial
For a detailed walk-through on building, modifying, and testing, see this tutorial on how to start contributing to OSTree.