|
| 1 | +# Contributing to Clouddrift |
| 2 | + |
| 3 | +Thank you for your interest in contributing! We look forward to seeing your ideas and working with you to improve the `clouddrift` library 😄 |
| 4 | + |
| 5 | +It should be noted that this contributing guide took heavy inspiration from the [Awkward Array](https://github.com/scikit-hep/awkward/blob/main/CONTRIBUTING.md) project. |
| 6 | + |
| 7 | +## Code of Conduct |
| 8 | +This project follows [NumFOCUS code of conduct](https://numfocus.org/code-of-conduct>). The short version is: |
| 9 | + |
| 10 | +- Be kind to others. Do not insult or put down others. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate. |
| 11 | +- All communication should be appropriate for a professional audience including people of many different backgrounds. Sexual language and imagery is not appropriate. |
| 12 | +- We are dedicated to providing a harassment-free community for everyone, regardless of gender, sexual orientation, gender identity and expression, disability, physical appearance, body size, race, or religion. |
| 13 | +- We do not tolerate harassment of community members in any form. |
| 14 | + |
| 15 | +Thank you for helping make this a welcoming, friendly community for all. |
| 16 | + |
| 17 | +### Where to start |
| 18 | + |
| 19 | +The front page for the Clouddrift project is on [clouddrift.org](https://clouddrift.org). This leads directly to some of the motivations behind building the library and a quick summary of the ragged array data structure. On the same web page you can also find links to examples showcasing the ragged array data structure and some of the datasets we transform and make available through the library. |
| 20 | + |
| 21 | +### Reporting issues and requesting feature requests |
| 22 | +Running into a bug or having performance issues? fill in a [Bug report](https://github.com/cloud-drift/clouddrift/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%F0%9F%90%9B+%3Cnice+descriptive+title%3E). |
| 23 | + |
| 24 | +Have a feature in mind you'd like to see implemened, refactoring changes you want to suggest or tools you think would help improve the project? Create a [Feature request](https://github.com/cloud-drift/clouddrift/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%3Cselect-one%3A+%E2%AD%90+%28feature%29+%7C++%F0%9F%94%8E+%28refactor%2Fdocs%29+%7C+%F0%9F%94%A7+%28tools%29%3E+%3Cdescriptive+title+here%3E). |
| 25 | + |
| 26 | +### Contributing a pull request |
| 27 | + |
| 28 | +Feel free to [open pull requests in GitHub](https://github.com/Cloud-Drift/clouddrift/pulls) from your [forked repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) when you start working on the problem. We recommend opening the pull request early so that we can see your progress and communicate about it. (Note that you can `git commit --allow-empty` to make an empty commit and start a pull request before you even have new code.) |
| 29 | + |
| 30 | +Please [make the pull request a draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to indicate that it is in an incomplete state and shouldn't be merged until you click "ready for review". |
| 31 | + |
| 32 | +### Getting your pull request reviewed |
| 33 | + |
| 34 | +Currently, we have two regular reviewers of pull requests: |
| 35 | + |
| 36 | + * Kevin Santana ([kevinsantana11](https://github.com/kevinsantana11)) |
| 37 | + * Shane Elipot ([selipot](https://github.com/selipot)) |
| 38 | + |
| 39 | +You can request a review from one of us or just comment in GitHub that you want a review and we'll see it. Only one review is required to be allowed to merge a pull request. We'll work with you to get it into shape. |
| 40 | + |
| 41 | +If you're waiting for a response and haven't heard in a few days, it's possible that we forgot/got distracted/thought someone else was reviewing it/thought we were waiting on you, rather than you waiting on us—just write another comment to remind us. |
| 42 | + |
| 43 | +### Git practices |
| 44 | + |
| 45 | +Unless you ask us not to, we might commit directly to your pull request as a way of communicating what needs to be changed. That said, most of the commits on a pull request are from a single author: corrections and suggestions are exceptions. |
| 46 | + |
| 47 | +The titles of pull requests (and therefore the merge commit messages) should follow the convention described below: |
| 48 | +``` |
| 49 | +<descriptive emoji> <descriptive title goes here> |
| 50 | +
|
| 51 | +examples: |
| 52 | +
|
| 53 | +⚡ improve dataset loading time |
| 54 | +⭐ include new ibtracs dataset |
| 55 | +🐛 x feature doesn't work on windows |
| 56 | +
|
| 57 | +Common emojis to use are as follow: |
| 58 | +
|
| 59 | +⭐ New / changed feature |
| 60 | +❗ Deprecation of a feature |
| 61 | +⛔ Removal of feature |
| 62 | +🐛 Bugfix |
| 63 | +⚡ Performance/memory improvements |
| 64 | +🔍 Documentation, refactoring |
| 65 | +🔧 Tooling/Build scripts/CI (other non-application changes) |
| 66 | +``` |
| 67 | + |
| 68 | +Almost all pull requests are merged with the "squash and merge" feature, so details about commit history within a pull request are hidden from the `main` branch's history. Feel free, therefore, to commit with any frequency you're comfortable with. |
| 69 | + |
| 70 | + |
| 71 | +### Preparing your environment |
| 72 | + |
| 73 | +1. Get the code |
| 74 | + |
| 75 | +``` |
| 76 | +git clone https://github.com/cloud-drift/clouddrift |
| 77 | +cd clouddrift/ |
| 78 | +``` |
| 79 | + |
| 80 | +2. Install library dependencies |
| 81 | + |
| 82 | +with pip: |
| 83 | + |
| 84 | +``` |
| 85 | +python3 -m venv .venv |
| 86 | +source .venv/bin/activate |
| 87 | +pip install . |
| 88 | +``` |
| 89 | + |
| 90 | +with conda: |
| 91 | + |
| 92 | +``` |
| 93 | +conda env create -f environment.yml |
| 94 | +conda activate clouddrift |
| 95 | +``` |
| 96 | + |
| 97 | +### Testing |
| 98 | + |
| 99 | +1. pre-requisite step: [Preparing your environment](#preparing-your-environment) |
| 100 | + |
| 101 | +2. Install testing dependencies |
| 102 | + |
| 103 | +with pip: |
| 104 | + |
| 105 | +``` |
| 106 | +pip install matplotlib cartopy |
| 107 | +``` |
| 108 | + |
| 109 | +with conda: |
| 110 | + |
| 111 | +``` |
| 112 | +conda install matplotlib-base cartopy |
| 113 | +``` |
| 114 | + |
| 115 | +3. Run the test suite: |
| 116 | + |
| 117 | +``` |
| 118 | +python -m unittest tests/*.py |
| 119 | +``` |
| 120 | + |
| 121 | +### Building locally and installing |
| 122 | +This can be useful for understanding how the package is built, testing the process and can be leveraged for testing |
| 123 | +experimental versions of the library from a users perspective. |
| 124 | + |
| 125 | +1. Install the build dependencies |
| 126 | + |
| 127 | +with pip: |
| 128 | +``` |
| 129 | +pip install build twine docutils |
| 130 | +``` |
| 131 | + |
| 132 | +with conda: |
| 133 | +``` |
| 134 | +conda install build twine docutils |
| 135 | +``` |
| 136 | + |
| 137 | +2. Generate the wheel (.whl) and tarball (tar.gz) distribution package(s): |
| 138 | +``` |
| 139 | +python -m build |
| 140 | +``` |
| 141 | + |
| 142 | +3. Install the distribution package |
| 143 | + |
| 144 | +with pip: |
| 145 | +``` |
| 146 | +pip install dist/clouddrift*.whl |
| 147 | +``` |
| 148 | + |
| 149 | +### Automatic formatting and linting |
| 150 | + |
| 151 | +The Clouddrift project uses the [`ruff`](https://github.com/astral-sh/ruff) tool for formatting the code and linting. We also leverage [`mypy`](https://github.com/python/mypy) for static typing. Please see the section on [Automated Processes](#automated-processes) to learn about how these tools are used prior to accepting pull requests. |
| 152 | + |
| 153 | +1. Install development dependencies |
| 154 | + |
| 155 | +with pip: |
| 156 | + |
| 157 | +``` |
| 158 | +pip install ruff mypy |
| 159 | +``` |
| 160 | + |
| 161 | +with conda: |
| 162 | + |
| 163 | +``` |
| 164 | +conda install ruff mypy |
| 165 | +``` |
| 166 | + |
| 167 | +2. Install any missing library type stubs: |
| 168 | + |
| 169 | +``` |
| 170 | +mypy --install-types |
| 171 | +``` |
| 172 | + |
| 173 | +* To format your code: |
| 174 | + |
| 175 | +``` |
| 176 | +ruff format clouddrift tests |
| 177 | +``` |
| 178 | + |
| 179 | +* To Lint your code: |
| 180 | + |
| 181 | +``` |
| 182 | +ruff check clouddrift tests |
| 183 | +``` |
| 184 | + |
| 185 | +* To perform static type analysis: |
| 186 | + |
| 187 | +``` |
| 188 | +mypy --config-file pyproject.toml |
| 189 | +``` |
| 190 | + |
| 191 | +### Automated Processes |
| 192 | + |
| 193 | +* `unittest` `ruff` and `mypy` are executed as part of the CI process. If any unit tests fail or styling, linting or typing errors are found |
| 194 | +the process will fail and will block pull requests from being merged. |
| 195 | + |
| 196 | +### Building documentation locally |
| 197 | +This is useful if you want to inspect the documentation that gets generated |
| 198 | + |
| 199 | +* pre-requisite step: [Building locally and installing](#building-locally-and-installing) necessary for sphinx to find class/module references |
| 200 | + |
| 201 | + |
| 202 | +1. Go into the docs directory: |
| 203 | +``` |
| 204 | +cd docs |
| 205 | +``` |
| 206 | + |
| 207 | +2. Install the Sphinx documentation generation dependencies: |
| 208 | +``` |
| 209 | +pip install -r requirements.txt |
| 210 | +``` |
| 211 | + |
| 212 | +3. Generate the new documentation: |
| 213 | +``` |
| 214 | +make html |
| 215 | +``` |
| 216 | + |
| 217 | +### Releases |
| 218 | + |
| 219 | +Currently, only one person can deploy releases: |
| 220 | + |
| 221 | + * Kevin Santana ([kevinsantana11](https://github.com/kevinsantana11)) |
| 222 | + |
| 223 | +If you need your merged pull request to be deployed in a release, just ask! |
| 224 | + |
| 225 | +#### `clouddrift` releases |
| 226 | +To make an `clouddrift` release you must do it as part of a pull request: |
| 227 | + |
| 228 | +* Be sure to increase the version number in `pyproject.toml` in accordance with the [Semantic Versioning Specification](https://semver.org/) |
| 229 | +* Once the PR is merged locally update your local main branch |
| 230 | + * `git checkout main` |
| 231 | + * `git pull` |
| 232 | +* Tag the release with the new version number as so: vX.Y.Z (e.g. - v0.32.0, v1.10.0, etc...) |
| 233 | + * `git tag vX.Y.Z` (e.g. - `git tag v0.32.0`) |
| 234 | +* Push the tag up (origin here is the remote repository for the `clouddrift` repository of the `Cloud-Drift` organization on GitHub) |
| 235 | + * `git push origin vX.Y.Z` (e.g. - `git push origin v0.32.0`) |
| 236 | +* Create a [new release](https://github.com/Cloud-Drift/clouddrift/releases/new) |
| 237 | + * Choose the tag you just pushed up (e.g. - v0.32.0) |
| 238 | + * Hit `Generate release notes` |
| 239 | + * Hit `Publish Release` if you think the release notes are descriptive otherwise you can create a draft to be reviewed by the community. |
| 240 | + |
| 241 | +**Important:** Once you publish the release, an automated process will be triggered creating a new distribution for the release which is then published to PYPI. |
| 242 | +Because we also maintain a `conda-forge` package a PR will be made within a few hours of the release on the `clouddrift-feedstock` [package](https://github.com/conda-forge/clouddrift-feedstock) as a `conda-forge` bot has detected a new release on PYPI. Once this is merged in, a job will begin building the package to be merged into the channel. |
0 commit comments