Skip to content

Commit bd4cc85

Browse files
drbenvincentdrbenvincent
authored
Merge pull request #182 from pymc-labs/update-contributing
Add more information to help contributors to the repo
2 parents 4a12f93 + 6f7d6eb commit bd4cc85

File tree

1 file changed

+134
-80
lines changed

1 file changed

+134
-80
lines changed

‎CONTRIBUTING.md

Lines changed: 134 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,171 @@
1-
# CONTRIBUTING
1+
# Guidelines for Contributing
22

3-
This repository is under active development by a small number of contributors at the moment. Once the code and API has settled a bit we will open up and welcome contributions. But not yet.
3+
CausalPy welcomes contributions from interested individuals or groups. These guidelines are provided to give potential contributors information to make their contribution compliant with the conventions of the CausalPy project, and maximize the probability of such contributions are merged as quickly and efficiently as possible. Contributors need not be experts, but should be interested in the project, willing to learn, and share knowledge.
44

5-
## Setup for local development
5+
There are 4 main ways of contributing to the CausalPy project (in ascending order of difficulty or scope):
66

7-
1. Create a new environment using Python >=3.8, for example 3.10
7+
1. Submitting issues related to bugs or desired enhancements.
8+
2. Contributing or improving the documentation (docs) or examples.
9+
3. Fixing outstanding issues (bugs) with the existing codebase. They range from low-level software bugs to higher-level design problems.
10+
4. Adding new or improved functionality to the existing codebase.
811

9-
```
10-
conda create --name CausalPy python=3.10
11-
```
12+
Items 2-4 require setting up a local development environment, see [Local development steps](#Local-development-steps) for more information.
1213

13-
2. Activate environment:
14+
## Opening issues
1415

15-
```
16-
conda activate CausalPy
17-
```
16+
We appreciate being notified of problems with the existing CausalPy code. We prefer that issues be filed the on [Github Issue Tracker](https://github.com/pymc-labs/CausalPy/issues), rather than on social media or by direct email to the developers.
1817

19-
3. Install the package in editable mode
18+
Please verify that your issue is not being currently addressed by other issues or pull requests by using the GitHub search tool to look for key words in the project issue tracker.
2019

21-
```
22-
pip install -e .
23-
```
20+
## Contributing code via pull requests
2421

25-
4. Install development dependencies
22+
While issue reporting is valuable, we strongly encourage users who are inclined to do so to submit patches for new or existing issues via pull requests. This is particularly the case for simple fixes, such as typos or tweaks to documentation, which do not require a heavy investment of time and attention.
2623

27-
```
28-
pip install causalpy[dev]
29-
pip install causalpy[docs]
30-
pip install causalpy[test]
31-
pip install causalpy[lint]
32-
```
24+
Contributors are also encouraged to contribute new code to enhance CausalPy's functionality, via pull requests.
3325

34-
If that fails, try:
26+
The preferred workflow for contributing to CausalPy is to fork the GitHub repository, clone it to your local machine, and develop on a feature branch.
3527

36-
```
37-
pip install 'causalpy[dev]'
38-
pip install 'causalpy[docs]'
39-
pip install 'causalpy[test]'
40-
pip install 'causalpy[lint]'
41-
```
28+
For more instructions see the [Pull request checklist](#pull-request-checklist)
4229

43-
It may also be necessary to [install](https://pandoc.org/installing.html) `pandoc`. On a mac, I run `brew install pandoc`.
30+
## Local development steps
4431

45-
5. You may also need to run this to get pre-commit checks working
32+
1. If you have not already done so, fork the [project repository](https://github.com/pymc-labs/CausalPy) by clicking on the 'Fork' button near the top right of the main repository page. This creates a copy of the code under your GitHub user account.
4633

47-
```
48-
pre-commit install
49-
```
34+
1. Clone your fork of the `CausalPy` repo from your GitHub account to your local disk, and add the base repository as a remote:
5035

51-
6. Note: You may have to run the following command to make Jupyter Lab aware of the `CausalPy` environment.
36+
```bash
37+
git clone [email protected]:<your GitHub handle>/CausalPy.git
38+
cd CausalPy
39+
git remote add upstream [email protected]:pymc-labs/CausalPy.git
40+
```
5241

53-
```
54-
python -m ipykernel install --user --name CausalPy
55-
```
42+
1. Create a feature branch (e.g. `my-feature`) to hold your development changes:
5643

57-
## Building the documentation locally
44+
```bash
45+
git checkout -b my-feature
46+
```
5847

59-
Ensure the right packages (in `requirements-docs.txt`) are available in the environment. See the steps above.
48+
Always use a feature branch. It's good practice to never routinely work on the `main` branch of any repository.
6049
61-
A local build of the docs is achieved by:
50+
1. Create a new environment using Python >=3.8, for example 3.11
6251
63-
```bash
64-
cd docs
65-
make html
66-
```
52+
```bash
53+
conda create --name CausalPy python=3.11
54+
```
6755
68-
Sometimes not all changes are recognised. In that case run this (again from within the `docs` folder):
56+
Activate the environment.
6957
70-
```bash
71-
make clean && make html
72-
```
58+
```bash
59+
conda activate CausalPy
60+
```
7361
74-
Docs are built in `docs/_build`, but these docs are _not_ committed to the GitHub repository due to `.gitignore`.
62+
Install the package (in editable mode) and its development dependencies:
7563
76-
## Remote documentation
64+
```bash
65+
pip install -e .
66+
```
7767
78-
Documentation is hosted on https://causalpy.readthedocs.io/. New remote builds are triggered automatically whenever there is an update to the `main` branch.
68+
Install development dependencies
7969
80-
The `.readthedocs.yaml` file contains the configurations for the remote build.
70+
```
71+
pip install 'causalpy[dev]'
72+
pip install 'causalpy[docs]'
73+
pip install 'causalpy[test]'
74+
pip install 'causalpy[lint]'
75+
```
8176
82-
If there are autodoc issues/errors in remote builds of the docs, we need to add all package dependencies (in `requirements.txt`) into the list `autodoc_mock_imports` in `docs/config.py`.
77+
It may also be necessary to [install](https://pandoc.org/installing.html) `pandoc`. On a mac, run `brew install pandoc`.
8378
84-
## New releases
79+
Set [pre-commit hooks](https://pre-commit.com/)
8580
86-
### Test release to `test.pypi.org` (manual)
81+
```bash
82+
pre-commit install
83+
```
8784
88-
1. Bump the release version in `causalpy/version.py` and `pyproject.toml`.
89-
2. Build locally and upload to test.pypi.org. Full instructions here https://packaging.python.org/en/latest/tutorials/packaging-projects/. _Note that this requires username and password for test.pypi.org_. In the root directory type the following:
90-
```bash
91-
rm -rf dist
92-
python3 -m build
93-
python3 -m twine upload --repository testpypi dist/*
94-
```
95-
3. At this point the updated build is available on test.pypi.org. We can test that this is working as expected by installing (into a test environment) from test.pypi.org with
85+
If you are editing or writing new examples in the form of Jupyter notebooks, you may have to run the following command to make Jupyter Lab aware of the `CausalPy` environment.
86+
87+
```
88+
python -m ipykernel install --user --name CausalPy
89+
```
90+
91+
1. You can then work on your changes locally, in your feature branch. Add changed files using `git add` and then `git commit` files:
92+
93+
```bash
94+
git add modified_files
95+
git commit -m "Message summarizing commit changes"
96+
```
97+
98+
to record your changes locally.
99+
After committing, it is a good idea to sync with the base repository in case there have been any changes:
100+
101+
```bash
102+
git fetch upstream
103+
git rebase upstream/main
104+
```
105+
106+
Then push the changes to your GitHub account with:
107+
108+
```bash
109+
git push -u origin my-feature
110+
```
111+
112+
1. Before you submit a Pull Request, follow the [Pull request checklist](#pull-request-checklist).
113+
114+
1. Finally, to submit a pull request, go to the GitHub web page of your fork of the CausalPy repo. Click the 'Pull request' button to send your changes to the project's maintainers for review. This will send an email to the committers.
115+
116+
## Pull request checklist
117+
118+
We recommend that your contribution complies with the following guidelines before you submit a pull request:
119+
120+
- If your pull request addresses an issue, please use the pull request title to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is created.
121+
122+
- All public methods must have informative docstrings with sample usage when appropriate.
123+
124+
- To indicate a work in progress please mark the PR as `draft`. Drafts may be useful to (1) indicate you are working on something to avoid duplicated work, (2) request broad review of functionality or API, or (3) seek collaborators.
125+
126+
- All other tests pass when everything is rebuilt from scratch. Tests can be run with:
127+
128+
```bash
129+
make test
130+
```
131+
132+
- When adding additional functionality, either edit an existing example, or create a new example (typically in the form of a Jupyter Notebook). Have a look at other examples for reference. Examples should demonstrate why the new functionality is useful in practice.
133+
134+
- Documentation and high-coverage tests are necessary for enhancements to be accepted.
135+
136+
- Documentation follows [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
137+
138+
- If you have changed the documentation, you should [build the docs locally](#Building-the-documentation-locally) and check that the changes look correct.
139+
140+
- Run any of the pre-existing examples in `CausalPy/docs/source/*` that contain analyses that would be affected by your changes to ensure that nothing breaks. This is a useful opportunity to not only check your work for bugs that might not be revealed by unit test, but also to show how your contribution improves CausalPy for end users.
141+
142+
- Your code passes linting tests. Run the line below to check linting errors:
143+
144+
```bash
145+
make check_lint
146+
```
147+
If you want to fix linting errors automatically, run
148+
149+
```bash
150+
make lint
151+
```
152+
153+
## Building the documentation locally
154+
155+
A local build of the docs is achieved by:
96156

97157
```bash
98-
conda create -n causalpy-test python
99-
conda activate causalpy-test
100-
python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ causalpy
158+
cd docs
159+
make html
101160
```
102161

103-
4. Now load a python or ipython session and follow the quickstart instructions to confirm things work.
104-
105-
### Actual release to `pypi.org` (manual)
162+
Sometimes not all changes are recognised. In that case run this (again from within the `docs` folder):
106163

107-
1. Bump the release version in `causalpy/version.py` and `pyproject.toml` (if not done in the previous step). This is automatically read by `setup.py` and `docs/config.py`.
108-
2. Push this to a branch, open a pull request, and merge into main.
109-
3. Manually draft a new release [here](https://github.com/pymc-labs/CausalPy/releases), making sure to hit 'generate release notes'.
110-
4. Build locally and upload to pypi.org. In the root directory:
111164
```bash
112-
rm -rf dist
113-
python3 -m build
114-
python3 -m twine upload dist/*
165+
make clean && make html
115166
```
116-
5. Readthedocs:
117-
- Docs should be built remotely every time there is a pull request
118-
- See here https://docs.readthedocs.io/en/stable/tutorial/#versioning-documentation for versioning the docs
167+
168+
Docs are built in `docs/_build`, but these docs are _not_ committed to the GitHub repository due to `.gitignore`.
119169

120170
## Overview of code structure
121171

@@ -130,3 +180,7 @@ Classes
130180

131181
Packages
132182
![](img/packages.png)
183+
184+
---
185+
186+
This guide takes some inspiration from the [Bambi guide to contributing](https://github.com/bambinos/bambi/blob/main/docs/CONTRIBUTING.md)

0 commit comments

Comments
 (0)