|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the Application Study Tool! |
| 4 | +Please read this guide for general guidelines to follow, which borrows heavily |
| 5 | +from those used by the Opentelemetry Collector. |
| 6 | + |
| 7 | +## How to contribute |
| 8 | + |
| 9 | +### Before you start |
| 10 | + |
| 11 | +Comment on the issue that you want to work on so we can assign it to you and |
| 12 | +clarify anything related to it. |
| 13 | + |
| 14 | +If you would like to work on something that is not listed as an issue, |
| 15 | +please create an issue and describe your proposal. It is best to do this |
| 16 | +in advance so that maintainers can decide if the proposal is a good fit for |
| 17 | +this repository. This will help avoid situations when you spend significant time |
| 18 | +on something that maintainers may decide this repo is not the right place for. |
| 19 | + |
| 20 | +Follow the instructions below to create your PR. |
| 21 | + |
| 22 | +### Fork |
| 23 | + |
| 24 | +In the interest of keeping this repository clean and manageable, you should |
| 25 | +work from a fork. To create a fork, click the 'Fork' button at the top of the |
| 26 | +repository, then clone the fork locally using `git clone |
| 27 | +git@github.com:USERNAME/application-study-tool.git`. |
| 28 | + |
| 29 | +You should also add this repository as an "upstream" repo to your local copy, |
| 30 | +in order to keep it up to date. You can add this as a remote like so: |
| 31 | + |
| 32 | +`git remote add upstream https://github.com/f5devcentral/application-study-tool.git` |
| 33 | + |
| 34 | +Verify that the upstream exists: |
| 35 | + |
| 36 | +`git remote -v` |
| 37 | + |
| 38 | +To update your fork, fetch the upstream repo's branches and commits, then merge |
| 39 | +your `development` with upstream's `development`: |
| 40 | + |
| 41 | +``` |
| 42 | +git fetch upstream |
| 43 | +git checkout development |
| 44 | +git merge upstream/development |
| 45 | +``` |
| 46 | + |
| 47 | +Remember to always work in a branch of your local copy, as you might otherwise |
| 48 | +have to contend with conflicts in `development`. |
| 49 | + |
| 50 | + |
| 51 | +## Required Tools |
| 52 | + |
| 53 | +Working with the project sources requires the following tools: |
| 54 | + |
| 55 | +1. [git](https://git-scm.com/) |
| 56 | +4. [docker](https://www.docker.com/) |
| 57 | + |
| 58 | +## Repository Setup |
| 59 | + |
| 60 | +Fork the repo and checkout by: |
| 61 | + |
| 62 | +``` |
| 63 | +$ git clone git@github.com:f5devcentral/application-study-tool.git |
| 64 | +``` |
| 65 | + |
| 66 | +Add your fork as an origin: |
| 67 | + |
| 68 | +```shell |
| 69 | +$ cd application-study-tool |
| 70 | +$ git remote add fork git@github.com:YOUR_GITHUB_USERNAME/application-study-tool.git |
| 71 | +``` |
| 72 | + |
| 73 | +## Creating a PR |
| 74 | + |
| 75 | +Checkout a new branch, make modifications, build locally, and push the branch to your fork |
| 76 | +to open a new PR: |
| 77 | + |
| 78 | +```shell |
| 79 | +$ git checkout development |
| 80 | +$ git checkout -b feature |
| 81 | +# edit |
| 82 | +$ git commit |
| 83 | +$ git push fork feature |
| 84 | +``` |
| 85 | + |
| 86 | +### Commit Messages |
| 87 | + |
| 88 | +Use descriptive commit messages. Here are [some recommendations](https://cbea.ms/git-commit/) |
| 89 | +on how to write good commit messages. |
| 90 | +When creating PRs GitHub will automatically copy commit messages into the PR description, |
| 91 | +so it is a useful habit to write good commit messages before the PR is created. |
| 92 | +Also, unless you actually want to tell a story with multiple commits make sure to squash |
| 93 | +into a single commit before creating the PR. |
| 94 | + |
| 95 | +When maintainers merge PRs with multiple commits, they will be squashed and GitHub will |
| 96 | +concatenate all commit messages right before you hit the "Confirm squash and merge" |
| 97 | +button. Maintainers must make sure to edit this concatenated message to make it right before merging. |
| 98 | +In some cases, if the commit messages are lacking the easiest approach to have at |
| 99 | +least something useful is copy/pasting the PR description into the commit message box |
| 100 | +before merging (but see the above paragraph about writing good commit messages in the first place). |
0 commit comments