diff options
author | Andrew Newdigate <andrew@gitlab.com> | 2017-07-25 12:54:22 +0300 |
---|---|---|
committer | Andrew Newdigate <andrew@gitlab.com> | 2017-07-25 12:54:22 +0300 |
commit | 454e246ba5e4ba9d55790a9ca7370eab583b71d6 (patch) | |
tree | a3cbafff6521ddfbd2c9ae6cd730208bde243d6c /CONTRIBUTING.md | |
parent | 22595ab2fcc7cdca38907f99e8cb90765632a8dd (diff) |
Updated documentation
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa0c911e5..4310511ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,3 +23,91 @@ We only create GitLab CE changelog entries for two types of merge request: - adding a feature flag for one or more Gitaly RPC's (meaning the RPC becomes available for trials) - removing a feature flag for one or more Gitaly RPC's (meaning everybody is using a given RPC from that point on) + +## Gitaly Maintainers + +|*Maintainer *| +|--------------------| +|@jacobvosmaer-gitlab| + +## Development Process + +We use long-running "~Conversation" issues (aka meta-issues) to track the progress of endpoint migrations and other work. + +These issues can be tracked on the [Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341). + +Conversation issues help us track migrations through the stages of the [migration process](doc/MIGRATION_PROCESS.md): +- ~"Migration:Ready-for-Development" +- ~"Migration:RPC-Design" +- ~"Migration:Server-Impl" +- ~"Migration:Client-Impl" +- ~"Migration:Ready-for-Testing" +- ~"Migration:Acceptance-Testing" +- ~"Migration:Disabled" +- ~"Migration:Opt-In" +- ~"Migration:Opt-Out" +- ~"Migration:Mandatory" + +While migration may take several releases from end-to-end, and, so that we can better track progress, each stage of the migration will +spawn it's own issue. These issues should generally not stay open for more than a week or two. + +## How to develop a migration + +1. **Select a migration endpoint**: select a migration from the [migration board](https://gitlab.com/gitlab-org/gitaly/boards/331341). These migrations are prioritised so choose one near the top. + - Assign the conversation issue to yourself so that others know that you are working on it. +1. **Build the RPC interface**: + - Using the RPC design in the issue, create a merge request in the [gitaly-proto](https://gitlab.com/gitlab-org/gitaly-proto) repo +1. **Build the Gitaly Server implementation** +1. **Build the client implementation**: this will be in one or more of GitLab-Workhorse, GitLab-Shell, GitLab-CE and GitLab-EE. +1. **Note**: you may find it more productive to work on the RPC interface, server and client implementations simultaneously + - Sometimes while building the server and client you may discover problems with the RPC interface + - For this reason, it can be easier to vendor your branch of `gitaly-proto` into your server and client branches during development + - In GitLab-CE and GitLab-Shell, custom versions of Gitaly can be specified in the `GITALY_SERVER_VERSION` file by using the syntax + `=my-branch-name` + - Remember to release a new version of `gitaly-proto` and `gitaly` and change the `GITALY_SERVER_VERSIONS` before review. +1. **Await a new release of GitLab**: + - Assign the conversation to the corresponding ["Post GitLab <Version> Deployment"](https://gitlab.com/gitlab-org/gitaly/milestones/) + milestone. +1. **Perform Acceptance Testing** + - We use feature toggles to gradually enable migration endpoints while monitoring their performance and status + - If a critical bug is discovered, it's disable the feature toggle and move the conversation into the ~"Migration:Disabled" columm + on the [migration board](https://gitlab.com/gitlab-org/gitaly/boards/331341) until a fix has been released. + +### Workflow + +1. The owner of a migration is responsible for moving conversation issues across the + [migration board](https://gitlab.com/gitlab-org/gitaly/boards/331341). +1. The Gitaly team uses a weekly Wednesday-Wednesday iteration with retrospectives every second week. +1. Work for the cycle should be assigned to the [appropriate Infrastructure Deliverable](https://gitlab.com/gitlab-org/gitaly/milestones/) milestone and tagged with the ~"Infrastructure Deliverable" label. + - Please **do not assign ~Conversation issues** to the weekly infrastructure deliverable milestone or the ~"Infrastructure Deliverable" label. + - ~Conversations are ongoing work-streams while ~"Infrastructure Deliverable" issues should be closed by the upcoming milestone. +1. To keep track of slipping issues, items which we have been unable to complete by the infrastructure deliverable milestone should be moved over to the next milestone and marked with ~"Moved:x1", ~"Moved:x2", ~"Moved:x3" etc + +## Reviews + +Merge requests need to **approval by at least two [Gitaly team members](https://gitlab.com/groups/gl-gitaly/group_members)**. + +If a merge request will affect code that cannot be conditionally disabled via [feature flags](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11747) then at least one of the approvers should be a **Gitaly maintainer**. + +Examples of code that **requires maintainer approval** include: +* Configuration management +* Process startup or shutdown +* Shared utility classes such as stream utilities, etc + +Examples of code that **does not require maintainer approval** include: +* Build script changes (does not run in production) +* Testing changes (does not run in production) +* Migration endpoints (can be disabled via a feature flag) + +Additionally, if you feel that the change you are making is sufficiently complicated or just for your own confidence, +please feel free to assign a maintainer. + +## Gitaly Developer Quick-start Guide + +- Check the [README.md](README.md) file to ensure that you have the correct version of Go installed. +- To **lint**, **check formatting**, etc: `make verify` +- To **build**: `make build` +- To run **tests**: `make test` +- To get **coverage**: `make cover` +- **Clean**: `make clean` +- All-in-one: `make verify build test` |