Skip to content

Commit

Permalink
add contributing documentation (#457)
Browse files Browse the repository at this point in the history 
* add more contributing guidelines

* credit
  • Loading branch information
@ismael-mendoza
ismael-mendoza authored Sep 10, 2023
1 parent 128586e commit 7804219
Show file tree
Hide file tree
Showing 2 changed files with 130 additions and 32 deletions.
151 changes: 120 additions & 31 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,55 +1,144 @@
# Contributing
# Contributing to BlendingToolKit

Please makes sure to complete the following steps if you are interested in contributing to `BTK`.
Everyone is welcome to contribute to this project, and contributions can take many different forms, from helping to answer questions on the [discussions page](https://github.com/LSSTDESC/BlendingToolKit/discussions), to contributing to the code-base by making a Pull Request.

## Installing
In order to foster an open, inclusive, and welcoming community, all contributors agree to adhere to [BlendingToolKit code of conduct](CODE_OF_CONDUCT.md).

1. Start by git cloning the `BTK` repository:
## Contributing code using Pull Requests

Code contributions are most welcome. You can in particular look for GitHub issues marked as `contributions welcome` or `good first issue`. But you can also propose adding a new functionality, in which case you may find it beneficial to first open a GitHub issue to discuss the feature you want to implement ahead of opening a Pull Request.

Once you have some code you wish to contribute, you can follow this procedure to prepare a Pull Request:

- Fork the `BTK` repository under your own account, using the **Fork** button on the top right of the [GitHub page](https://github.com/LSSTDESC/BlendingToolKit).

- We use [poetry](https://python-poetry.org/docs/) for managing the dependencies of the project. You can install it with:

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

- Clone and pip install your fork of the repository like so:

```bash
git clone https://github.com/YOUR_USERNAME/BlendingToolKit
cd BlendingToolKit
poetry install
poetry shell # activate the virtual environment
```

This will install your local fork in editable mode, meaning you can directly modify source files in this folder without having to reinstall the package for them to be taken into account.

- Open a branch for your developments:

```bash
git checkout -b name-that-describes-my-feature
```

It's usually a good idea to name your branch after the issue you are working on, if any. For example:

```bash
git clone https://github.com/LSSTDESC/BlendingToolKit.git
git checkout -b i/42
```

2. It is recommended that you use `pdm` to manage the python environment for developing BTK. You can install pdm following the instructions [here](https://pdm.fming.dev/latest/#installation).
- Add your changes to the code using your favorite editor. You may at any moment test that everything is still working by running the test suite. From the root folder of the repository, run:

3. The following commands should install and activate a `btk` python environment managed by `pdm`:
```bash
poetry run pytest # or poetry shell; pytest
```

```bash
cd BlendingToolKit
- Once you are happy with your modifications, commit them, and push your changes to GitHub:

# install all python dependencies from pyproject.toml file
pdm install
```python
git add file_I_changed.py
git commit -m "a message that describes your modifications"
git push -set-upstream origin name-that-describes-my-feature
```

# activate pdm environment
eval $(pdm venv activate in-project)
- From your GitHub interface, you should now be able to open a Pull Request to the BlendingToolKit repository.

# install the git hook scripts
pre-commit install
Before submitting your PR, have a look at the procedure documented below.

### Checklist before opening a Pull Request

- Pull Requests should be self-contained and limited in scope, otherwise they become too difficult to review. If your modifications are broad, consider opening several smaller Pull Requests.

- Make sure your fork and branch are up-to-date with the `dev` branch of BTK. To update your local branch, you may do so from the GitHub interface, or you may use this CLI command:

```bash
git remote add upstream http://www.github.com/GalSim-developers/BlendingToolKit # Only needs to be done once.
git fetch upstream
git rebase upstream/dev # This will update your local branch with the latest changes from the dev branch.
```

- Make sure the unit tests still work:

```bash
poetry run pytest
```

Ideally there should be some new unit tests for the new functionality, unless the work is completely covered by existing unit tests.

- Make sure your code conforms to the [Black](https://github.com/psf/black) style:

```bash
black .
```

- If your changes contain multiple commits, we encourage you to squash them into a single (or very few) commit, before opening the PR. To do so, you can using this command:

```bash
git rebase -i
```

If you have any problems with the installation, they are probably due to `galsim`. It is recommended that you follow the instructions for [installing galsim](https://galsim-developers.github.io/GalSim/_build/html/install.html) first (inside the `pdm` virtual environment), and then try again.
### Opening the Pull Request

## Pull Requests
- On the GitHub site, go to "Code". Then click the green "Compare and Review" button. Your branch is probably in the "Example Comparisons" list, so click on it. If not, select it for the "compare" branch.

1. Every contribution to BTK must be made in a form of a Pull Request (PR) can eventually be merged to the `dev` branch. (NOTE: Only the maintainer(s) can push to the `main` branch)
- Make sure you are comparing your new branch to the upstream `dev`. Press Create Pull Request button.

2. Every pull request must pass the workflows specified in `.github/workflows` before merging.
- Give a brief title. (We usually leave the branch number as the start of the title.)

- The tool known as `pre-commit` will make it easy to for you to pass the linting workflow, install it in your local repository by running `pre-commit install`.
- Explain the major changes you are asking to be code reviewed. Often it is useful to open a second tab in your browser where you can look through the diff yourself to remind yourself of all the changes you have made.

- For `BTK` we are using the `black` formatter, you can format your code by running `black .` which formats all python files accessible from your current directory. If you have an IDE that you like there are also [options](https://black.readthedocs.io/en/stable/editor_integration.html) to format on save.
### After submitting the pull request

- You can run all the tests locally by simply running `pytest` inside your local BTK repository.
- Check to make sure that the PR can be merged cleanly. If it can, GitHub will report that "This branch has no conflicts with the base branch." If it doesn't, then you need to merge from master into your branch and resolve any conflicts.
- If you get stuck by `pre-commit` errors, please ping us on your PR.
- Wait a few minutes for the continuous integration tests to be run. Then make sure that the tests reports no errors. If not, click through to the details and try to figure out what is causing the error and fix it.
3. If other branches were merged while you were working on this PR to the `dev` branch, then you will to rebase before merging:
### After code review
```bash
git rebase origin/dev
# follow the instructions and resolve conflicts...
# Feel free to ask other developers if you are not sure of the conflicts.
git push --force
```
- Once at least 1 and preferably 2 people have reviewed the code, and you have responded to all of their comments, we generally solicit for "any other comments" and give people a few more days before merging.
- Click the "Merge pull request" button at the bottom of the PR page.
- Click the "Delete branch" button.
## Guidelines for Code Style and Documentation
### Code Style
In this project we follow the [Black](https://github.com/psf/black) code formatting guidelines` (Any color you like...) This means that all code should be automatically formatted using Black and CI will fail if that's not the case.

Black should be automatically installed when you install the project with `poetry install`.

And run it manually from the root directory of your local clone with `black .`

We highly recommend installing `pre-commit`, which will take care of trailing whitespace, checking for large files, and stripping
notebook metadata (keeping output).

```bash
pre-commit install
```

And that's all you need to do from now on.
### Documentation style
BlendingToolKit follows the google format: <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>
## Credit
4. Finally, ask for at least one approving review from [@ismael-mendoza](https://github.com/ismael-mendoza) or other collaborators.
This file was adapted from JAX-Galsim's [CONTRIBUTING.md](https://github.com/GalSim-developers/JAX-GalSim/edit/main/CONTRIBUTING.md)
11 changes: 10 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,4 +93,13 @@ In case of any issues and for details of required packages, please see the more

## Contributing

See our contributing guidelines at [CONTRIBUTING.md](https://github.com/LSSTDESC/BlendingToolKit/blob/main/CONTRIBUTING.md)
Everyone can contribute to this project, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document for details.

In short, to interact with the project you can:

- Ask or Answer questions on the [Discussions Q&A page](https://github.com/LSSTDESC/BlendingToolKit/discussions).
- Report a bug by opening a [GitHub issue](https://github.com/LSSTDESC/BlendingToolKit/issues).
- Open a [GitHub issue](https://github.com/LSSTDESC/BlendingToolKit/issue) or [Discussions](https://github.com/LSSTDESC/BlendingToolKit/discussions) to ask for feedback on a planned contribution.
- Submit a [Pull Request](https://github.com/LSSTDESC/BlendingToolKit/pulls) to contribute to the code.

Issues marked with `contributions welcome` or `good first issue` are particularly good places to start. These are great ways to learn more about the inner workings of BTK.

0 comments on commit 7804219

Please sign in to comment.