Contributing

Branching Practices

All reposities operate with a primary branch of main. When working on a new feature, you should branch from main and, then ready, create a Pull Request to merge your changes back into main.

Larger Projects

If we are working on a larger piece of piece, then creating a feature branch, then branching from this for smaller PRs/iterations is also acceptable.

Opening Draft Pull Requests

A good practice when you start a piece of work and commit your first changes is to open a Draft Pull Request attached to your branch. Within the PR description you should tag the relevant issue using the #XXX syntax per our guidance below. This improves transparency of progress and allows for feedback before the PR is merged.

To open a draft pull request:

1. Navigate to "Pull Requests" in the repository
2. Click the "New Pull Request" button
3. Select the branch you want to create a pull request from, and the corresponding target branch (what you're merging into)
4. Click "Create pull request"
5. Under the "Reviewers" section, select "Convert to draft"

Pull Requests

Pull Requests in GitHub should always contains a description of what has changed and why. Where possible, they should link to an issue/task in GitHub Projects that will be closed as a result of the Pull Request being merged.

Descriptions

Always ensure your Pull Requests link to an appropriate issue. The following phrases are recommended:

• "Closes #20" - This will automatically close the issue when the Pull Request is merged.
• "Fixes #20" - This will automatically close the issue when the Pull Request is merged.
• "Part of #20" - This will create a link to the relevant issue, but not close it when this PR is merged.

Reviews

Every review requires at least one approval. As part of your review you need to cover:

• Admin: Does the MR describe the changes made, and link to the appropriate issue/task in Jira?
• Tests: Are any appropriate tests added or updated?
• Docs: Are there any appropriate docs that need updating to reflect the changes made?
• Performance: Is the code performant and efficient?

Proposing Changes

Comments should be left that describe, in detail, why a MR may not be approved. If changes are requested, be helpful in your feedback to explain what changes are required, ven more helpful, if the changes are quick/minor, use GitLab's "Insert Suggestion" option to provide explicit code changes to the author of the MR.

Approve with SAML

An important element of our review process on GitLab is that each review must be explicitely authenticated. As such you cannot "Approve" via the "Your Review" button in GitLab, you will be met with a warning:

To approve this merge request, please enter your password. This project requires all approvals to be authenticated.

Instead, when approving, you must click the "Approve with SAML" button that appears inline of the issue:

New Repositories

Slack Notifications

To setup Slack notifications for a new repository, you can run the following command in the respective Slack channel where you want the notifications to appear:

/github subscribe es-profiler/my-repository

By default, this will subscribe to issues, pulls, commits, releases, deployments

If you want to reduce the number of notifications, you can consequently unsubscribe from the notifications you don't want to receive, e.g:

/github unsubscribe es-profiler/my-repository commits releases deployments

Which in this case would remove notifications about comments, releases and deployments.

There are other events available to subscribe to which can found found in the GitHub docs.

Experimental Projects

When making a new repository in ESPROFILER, and you are filling in the details of the new repository, there will be an option labelled "Experimental?". Toggle this on for any repositories that are being used as a home for in-progress code that may end up being thrown away, or for proof-of-concept projects.