Skip to content

Git designed for AI agents.

11.7 KB
Raw Blame

Contributing to Gitaly

Developer Certificate of Origin and License

By contributing to GitLab Inc., you accept and agree to the following terms and conditions for your present and future contributions submitted to GitLab Inc. Except for the license granted herein to GitLab Inc. and recipients of software distributed by GitLab Inc., you reserve all right, title, and interest in and to your Contributions.

All contributions are subject to the Developer Certificate of Origin and License.

This notice should stay as the first item in the CONTRIBUTING.md file.

Code of conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior can be reported by emailing [email protected].

This Code of Conduct is adapted from the Contributor Covenant, version 1.1.0, available at https://contributor-covenant.org/version/1/1/0/.

Style guides

For Gitaly code style, see STYLE.md.

For help text style guidance for this project, see the help text style guide.

Commits

In this project we value good commit hygiene. Clean commits make it much easier to discover when bugs have been introduced, why changes have been made, and what their reasoning was.

When you submit a merge request, expect the changes to be reviewed commit-by-commit. To make it easier for the reviewer, please submit your MR with nicely formatted commit messages and changes tied together step-by-step.

Write small, atomic commits

Commits should be as small as possible but not smaller than required to make a logically complete change. If you struggle to find a proper summary for your commit message, it's a good indicator that the changes you make in this commit may not be focused enough.

git add -p is useful to add only relevant changes. Often you only notice that you require additional changes to achieve your goal when halfway through the implementation. Use git stash to help you stay focused on this additional change until you have implemented it in a separate commit.

Split up refactors and behavioral changes

Introducing changes in behavior very often requires preliminary refactors. You should never squash refactoring and behavioral changes into a single commit, because that makes it very hard to spot the actual change later.

Tell a story

When splitting up commits into small and logical changes, there will be many interdependencies between all commits of your feature branch. If you make changes to simply prepare another change, you should briefly mention the overall goal that this commit is heading towards.

Describe why you make changes, not what you change

When writing commit messages, you should typically explain why a given change is being made. For example, if you have pondered several potential solutions, you can explain why you settled on the specific implementation you chose. What has changed is typically visible from the diff itself.

A good commit message answers the following questions:

  • What is the current situation?
  • Why does that situation need to change?
  • How does your change fix that situation?
  • Are there relevant resources which help further the understanding? If so, provide references.

Be succinct: give each question as much space as it needs and no more. A subtle change may warrant several paragraphs, while a self-evident one is served by a single line. What doesn't help either way is restating the diff or padding the reasoning, which only buries what the reviewer came for.

You may want to set up a message template to pre-populate your editor when executing git commit.

Use scoped commit subjects

Many projects typically prefix their commit subjects with a scope. For example, if you're implementing a new feature "X" for subsystem "Y", your commit message would be "Y: Implement new feature X". This makes it easier to quickly sift through relevant commits by simply inspecting this prefix.

Keep the commit subject short

Because commit subjects are displayed in various command line tools by default, keep the commit subject short. A good rule of thumb is that it shouldn't exceed 72 characters.

Mention the original commit that introduced bugs

When implementing bugfixes, it's often useful information to see why a bug was introduced and when it was introduced. Therefore, mentioning the original commit that introduced a given bug is recommended. You can use git blame or git bisect to help you identify that commit.

The format used to mention commits is typically the abbreviated object ID followed by the commit subject and the commit date. You may create an alias for this to have it easily available. For example:

$ git config alias.reference "show -s --pretty=reference"
$ git reference HEAD
cf7f9ffe5 (style: Document best practices for commit hygiene, 2020-11-20)

Use interactive rebases to arrange your commit series

Use interactive rebases to end up with commit series that are readable and therefore also easily reviewable one-by-one. Use interactive rebases to rearrange commits, improve their commit messages, or squash multiple commits into one.

Create fixup commits

When you create multiple commits as part of feature branches, you frequently discover bugs in one of the commits you've just written. Instead of creating a separate commit, you can easily create a fixup commit and squash it directly into the original source of bugs via git commit --fixup=ORIG_COMMIT and git rebase --interactive --autosquash.

Avoid merge commits

During development other changes might be made to the target branch. These changes might cause a conflict with your changes. Instead of merging the target branch into your topic branch, rebase your branch onto the target branch. Consider setting up git rerere to avoid resolving the same conflict over and over again.

Ensure that all commits build and pass tests

To keep history bisectable using git bisect, you should ensure that all of your commits build and pass tests. You can do this with interactive rebases, for example: git rebase -i --exec='make build format lint test' origin/master. This automatically builds each commit and verifies that they pass formatting, linting, and our test suite.

Changelog

Gitaly keeps a changelog that is generated:

  • When a new release is created.
  • From commit messages where a specific trailer is used.

The trailer should have the following format: Changelog: <option> where <option> is one of:

  • added
  • fixed
  • changed
  • deprecated
  • removed
  • security
  • performance
  • other

The commit title is used to generate a changelog entry.

Example

A great commit message could look something like:

package: Summarize change in 50 characters or less

The first line of the commit message is the summary. The summary should
start with a capital letter and not end with a period. Optionally
prepend the summary with the package name, feature, file, or piece of
the codebase where the change belongs to.

After an empty line the commit body provides a more detailed explanatory
text. This body is wrapped at 72 characters. The body can consist of
several paragraphs, each separated with a blank line.

The body explains the problem that this commit is solving. Focus on why
you are making this change as opposed to what (the code explains this).
Are there side effects or other counterintuitive consequences of
this change? Here's the place to explain them.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between

- Use a hanging indent

These guidelines are pretty similar to those described in the Git Book
[1]. If you like you can use footnotes to include a lengthy hyperlink
that would otherwise clutter the text.

You can provide links to the related issue, or the issue that's fixed by
the change at the bottom using a trailer. A trailer is a token, without
spaces, directly followed with a colon and a value. Order of trailers
doesn't matter.

1. https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines

Fixes: https://gitlab.com/gitlab-org/gitaly/-/issues/123
Changelog: added
Signed-off-by: Alice <[email protected]>

Gitaly Maintainers

This project is maintained by the members of @gl-gitaly.

Development Process

Gitaly follows the engineering process as described in the handbook, with the exception that our issue tracker is on the Gitaly project and there's no distinction between developers and maintainers. Every team member is equally responsible for a successful master pipeline and fixing security issues.

Merge requests are approved by Gitaly team members; REVIEWING.md describes how many approvals a change needs and how reviewers are chosen.

Review Process

See REVIEWING.md.

Gitaly Developer Quick-start Guide

See the beginner's guide.

Debugging

Set level = "debug" under [logging] in the configuration file to raise the log level. See Logging in Gitaly for the other keys and for what Gitaly logs.

Gitaly re-exports the GIT_TRACE* environment variables to the Git processes it spawns, so setting GIT_TRACE=true in Gitaly's environment reveals what Git does internally. Git writes that output to standard error, which Gitaly logs at debug level, so raise the log level first.

For instrumenting a single Git command rather than every one of them, Gitaly has a Trace2 integration instead. See Trace2 integration.

Metrics and profiling

Gitaly serves Prometheus metrics and the Go pprof endpoints on the address configured as prometheus_listen_addr. With Gitaly running from the GDK, that makes a CPU profile one command away:

go tool pprof -http=: http://localhost:9236/debug/pprof/profile

Swap profile for heap, goroutine, or any other pprof profile as needed. For what the metrics themselves are and where they are graphed, see Observability.