|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We would love for you to contribute to the luigi-tools package and help make it even better |
| 4 | +than it is today! As a contributor, here are the guidelines we would like you to follow: |
| 5 | +* [Issues and Bugs](#issue) |
| 6 | +* [Feature Requests](#feature) |
| 7 | +* [Submission Guidelines](#submit) |
| 8 | + |
| 9 | +## <a name="issue"></a> Got a question or found a bug? |
| 10 | + |
| 11 | +If you have a question or find a bug in the source code, you can help us by |
| 12 | +[submitting an issue](#submit-issue) to our [GitHub Repository][github]. Even better, you can |
| 13 | +[submit a Pull Request](#submit-pr) with a fix. |
| 14 | + |
| 15 | +## <a name="feature"></a> Missing a Feature? |
| 16 | + |
| 17 | +You can *request* a new feature by [submitting an issue](#submit-issue) to our |
| 18 | +[GitHub Repository][github]. If you would like to *implement* a new feature, please submit an |
| 19 | +issue with a proposal for your work first, to be sure that we can use it. Then |
| 20 | +[submit a Pull Request](#submit-pr) that points to this issue. |
| 21 | + |
| 22 | +Please consider what kind of change it is: |
| 23 | +* For a **Major Feature**, first open an issue and outline your proposal so that it can be |
| 24 | +discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, |
| 25 | +and help you to craft the change so that it is successfully accepted into the project. |
| 26 | +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). |
| 27 | + |
| 28 | +## <a name="submit"></a> Submission Guidelines |
| 29 | + |
| 30 | +### <a name="submit-issue"></a> Submitting an Issue |
| 31 | + |
| 32 | +Before you submit an issue, please search the issue tracker, maybe an issue for your problem |
| 33 | +already exists and the discussion might inform you of workarounds readily available. |
| 34 | + |
| 35 | +We want to fix all the issues as soon as possible, but before fixing a bug we need to reproduce |
| 36 | +and confirm it. In order to reproduce bugs we will need as much information as possible, a |
| 37 | +[Minimal Working Example](https://stackoverflow.com/help/minimal-reproducible-example), and |
| 38 | +preferably be in touch with you to gather information. |
| 39 | + |
| 40 | +### <a name="submit-pr"></a> Submitting a Pull Request (PR) |
| 41 | + |
| 42 | +When you wish to contribute to the code base, please consider the following guidelines: |
| 43 | +* Make a [fork](https://guides.github.com/activities/forking/) of this repository. |
| 44 | +* Make your changes in your fork, in a new git branch: |
| 45 | + ```shell |
| 46 | + git checkout -b my-fix-branch main |
| 47 | + ``` |
| 48 | + |
| 49 | +* Create your patch, **including appropriate test cases** (please note that the coverage must |
| 50 | + always be equal to 100%). |
| 51 | +* Run the full test suite, and ensure that all tests pass. |
| 52 | +* Commit your changes using a descriptive commit message. |
| 53 | + ```shell |
| 54 | + git commit -a |
| 55 | + ``` |
| 56 | + |
| 57 | + Note: the optional commit `-a` command line option will automatically **add** and **rm** edited |
| 58 | + files. |
| 59 | +* Push your branch to GitHub: |
| 60 | + ```shell |
| 61 | + git push origin my-fix-branch |
| 62 | + ``` |
| 63 | + |
| 64 | +* In GitHub, send a Pull Request to the `main` branch of the upstream repository of the relevant |
| 65 | + component. |
| 66 | +* If we suggest changes then: |
| 67 | + * Make the required updates. |
| 68 | + * Re-run the test suites to ensure tests are still passing. |
| 69 | + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): |
| 70 | + |
| 71 | + ```shell |
| 72 | + git rebase main -i |
| 73 | + git push -f |
| 74 | + ``` |
| 75 | + |
| 76 | +That's it! Thank you for your contribution! |
| 77 | +
|
| 78 | +#### After your pull request is merged |
| 79 | +
|
| 80 | +After your pull request is merged, you can safely delete your branch and pull the changes from the |
| 81 | +main (upstream) repository: |
| 82 | +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: |
| 83 | + ```shell |
| 84 | + git push origin --delete my-fix-branch |
| 85 | + ``` |
| 86 | +
|
| 87 | +* Check out the main branch: |
| 88 | + ```shell |
| 89 | + git checkout main |
| 90 | + ``` |
| 91 | +
|
| 92 | +* Delete the local branch: |
| 93 | + ```shell |
| 94 | + git branch -D my-fix-branch |
| 95 | + ``` |
| 96 | +
|
| 97 | +* Update your main with the latest upstream version: |
| 98 | + ```shell |
| 99 | + git pull --ff upstream main |
| 100 | + ``` |
| 101 | +
|
| 102 | +### <a name="release"></a> Releasing a new version |
| 103 | +
|
| 104 | +Releasing a new version can only be done by the maintainers. |
| 105 | +
|
| 106 | +The release process is the following: |
| 107 | +* Checkout the main branch and ensure your local version is up to date: |
| 108 | + ```shell |
| 109 | + git checkout main |
| 110 | + git pull |
| 111 | + ``` |
| 112 | +
|
| 113 | +* Create a new branch locally: |
| 114 | + ```shell |
| 115 | + git checkout -b release_X.Y.Z |
| 116 | + ``` |
| 117 | +
|
| 118 | +* Create a new temporary tag locally: |
| 119 | + ```shell |
| 120 | + git tag X.Y.Z |
| 121 | + ``` |
| 122 | +
|
| 123 | +* Update the CHANGELOG file using auto-changelog: |
| 124 | + ```shell |
| 125 | + auto-changelog |
| 126 | + ``` |
| 127 | +
|
| 128 | +* Commit the new changelog and remove the tag: |
| 129 | + ```shell |
| 130 | + git commit -m "Release X.Y.Z" |
| 131 | + git tag -d X.Y.Z |
| 132 | + git push origin |
| 133 | + ``` |
| 134 | +
|
| 135 | +* Open a new pull request from this branch and merge it. |
| 136 | +* Checkout the main branch and update it: |
| 137 | + ```shell |
| 138 | + git checkout main |
| 139 | + git pull |
| 140 | + ``` |
| 141 | +
|
| 142 | +* Create the final tag and push it: |
| 143 | + ```shell |
| 144 | + git tag X.Y.Z |
| 145 | + git push origin X.Y.Z |
| 146 | + ``` |
| 147 | +
|
| 148 | +After these steps the CI should automatically build the wheel and push it to pypi. |
| 149 | +
|
| 150 | +[github]: https://github.com/BlueBrain/morphology-workflows |
0 commit comments