Skip to content

Commit eeb6f11

Browse files
MichaelClerxMichaelClerx
authored
Merge pull request #104 from CardiacModelling/contrib-changelog
Add changelog and a provisional contributing.md
2 parents 62a0bd5 + 3226510 commit eeb6f11

5 files changed

Lines changed: 214 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1+
pcpostprocess/_version.py
12
/tests/test_data
23
/test_output
34
*__pycache__*
45
*.egg-info
56
*.DS_Store
7+
.coverage

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
This page lists the main changes made to pcpostprocess in each release.
4+
5+
## Unreleased
6+
- Added
7+
- [#104](https://github.com/CardiacModelling/pcpostprocess/pull/104) Added a CHANGELOG.md and CONTRIBUTING.md
8+
- Changed
9+
- Deprecated
10+
- Removed
11+
- Fixed
12+
13+
## [0.2.0] - 2025-11-11
14+
First official release.
15+

‎CONTRIBUTING.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Contributing to pcpostprocess
2+
3+
Contributions to pcpostprocess are always welcome!
4+
5+
We use [GIT](https://en.wikipedia.org/wiki/Git) and [GitHub](https://en.wikipedia.org/wiki/GitHub) to coordinate our work.
6+
When making changes, we try to follow the procedure below.
7+
8+
1. **Discuss proposed changes before starting any work.**
9+
Before coding, always create an [issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/about-issues) and disucss the proposed work.
10+
Something similar may already exist, be under development, or have been proposed and rejected - so this can save valuable time.
11+
12+
2. **Always work on branches**.
13+
Once the idea has been agreed upon, start coding in a new _branch_.
14+
If you're in the CardiacModelling team, you can create a [branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) directly in the main pcpostprocess repository.
15+
For outside contributions, you'll first need to [create a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
16+
17+
There are no rules for branch names, but try to make them relate to the issue, e.g. by including the issue number.
18+
19+
Commit your changes to your branch with useful, descriptive commit messages that will still make sense in years to come.
20+
21+
3. **Conform to style guidelines, and document every class, method, and argument.**
22+
For more information, see below.
23+
24+
**Note: as of 2025-11-11, we are still in the process of making `pcpostprocess` confirm to this rule.**
25+
26+
4. **Test locally, and ensure 100% test coverage**
27+
For more information, see below.
28+
29+
**Note: as of 2025-11-11, we are stillin the process of making `pcpostprocess` confirm to this rule.**
30+
31+
4. **Discuss code in a PR**
32+
When your code is finished, or warrants discussion, create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) (PR).
33+
In your branch, update the [Changelog](./CHANGELOG.md) with a link to this PR and a concise summary of the changes.
34+
Finally, request a review of the code.
35+
36+
## Project structure
37+
38+
`pcpostprocess` is written in [Python 3](https://en.wikipedia.org/wiki/Python_(programming_language)), but at the moment has a few **non-python dependencies** i.e. latex.
39+
40+
## Developer installation
41+
42+
**TODO: Once there is a "user" way to install, move the git clone etc. information here [#105](https://github.com/CardiacModelling/pcpostprocess/issues/105).**
43+
44+
```
45+
pip install -e .[test]
46+
```
47+
48+
## Style guidelines
49+
50+
Style checking is done with [flake8](http://flake8.pycqa.org/en/latest/).
51+
52+
To run locally, use
53+
```
54+
$ flake8
55+
```
56+
57+
Until Flake8 configuration supports [pyproject.toml](https://github.com/PyCQA/flake8/issues/234), it will be configured through [.flake8](./.flake8) ([syntax](http://flake8.pycqa.org/en/latest/user/configuration.html)).
58+
59+
In addition to the rules checked by flake8, we try to use single quotes (`'`) for strings, rather than double quotes (`"`) (but `"""` for docstrings).
60+
61+
### Spelling
62+
63+
**TODO WE SHOULD MAYBE DISCUSS WHICH ENGLISH TO USE? [#106](https://github.com/CardiacModelling/pcpostprocess/issues/106)**
64+
65+
### Import ordering
66+
67+
Import ordering is tested with [isort](https://pycqa.github.io/isort/index.html).
68+
69+
To run locally, use
70+
```
71+
isort --check-only --verbose ./pcpostprocess ./tests/
72+
```
73+
74+
Isort is configured in [pyproject.toml](./pyproject.toml) under the section `tool.isort`.
75+
76+
## Documentation
77+
78+
Every method and every class should have a [docstring](https://www.python.org/dev/peps/pep-0257/) that describes in plain terms what it does, and what the expected input and output is.
79+
80+
Each docstring should start with a one-line explanation.
81+
If more explanation is needed, this one-liner is followed by a blank line and more information in the following paragraphs.
82+
83+
**TODO: READTHEDOCS [#60](https://github.com/CardiacModelling/pcpostprocess/issues/60)**
84+
85+
**TODO: SYNTAX, RUNNING LOCALLY, ETC**
86+
87+
**TODO: EXAMPLES**
88+
89+
```
90+
cd doc
91+
make clean
92+
make html
93+
```
94+
95+
[reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html)
96+
[Sphinx](http://www.sphinx-doc.org/en/stable/)
97+
98+
## Testing
99+
100+
To run all unit tests, locally:
101+
102+
```
103+
$ python3 -m unittest
104+
```
105+
106+
To run a single test, use
107+
```
108+
$ python3 -m unittest TestClass.test_method
109+
```
110+
111+
### Unit tests
112+
113+
Testing is done with [unittest](https://docs.python.org/3/library/unittest.html).
114+
115+
Each method in `pcpostprocess` should have a unit test.
116+
117+
Tests should always aim to compare generated output with reference values, instead of just checking no errors are generated.
118+
119+
### Coverage
120+
121+
Coverage is checked with [coverage](https://coverage.readthedocs.io/en/latest/).
122+
123+
To run locally, use
124+
```
125+
coverage run -m unittest
126+
```
127+
and, if the tests pass, view the report with
128+
```
129+
coverage report
130+
```
131+
132+
### Github actions
133+
134+
Whenever changes are made to a branch with an open pull request, tests will be run using GitHub actions.
135+
136+
These are configured in a single workflow **TODO THIS IS BEING UPDATED ATM**
137+
138+
Coverage testing is run, and sent to [codecov.io](https://docs.codecov.io/docs) to generate [online reports](https://app.codecov.io/github/CardiacModelling/pcpostprocess).
139+
140+
## Logging changes
141+
142+
Each PR should add a line (or occasionally multiple lines) to [CHANGELOG.md](./CHANGELOG.md).
143+
This should be a very concise summary of the work done, and link to the PR itself for further info.
144+
Changes are classified as `Added`, `Changed`, `Deprecated`, `Removed`, or `Fixed`.
145+
146+
For example, the first entry in our Changelog was:
147+
```
148+
- Added
149+
- [#104](https://github.com/CardiacModelling/pcpostprocess/pull/104) Added a CHANGELOG.md and CONTRIBUTING.md
150+
```
151+
152+
## Packaging
153+
154+
This project uses a minimal [`setup.py`](./setup.py), and instead uses [pyproject.toml](./pyproject.toml).
155+
156+
### Versioning
157+
158+
Version numbers are not set in the code, but derived from git tags, using [setuptools-scm](https://setuptools-scm.readthedocs.io/en/latest/).
159+
This is run every time setuptools is run, e.g. with
160+
```
161+
pip install -e .[test]
162+
```
163+
164+
Versions numbers take the form `X.Y.Z` where X, Y, and Z are "major", "minor", and "revision" numbers.
165+
Changes to the public interface should be reflected in an updated minor version.
166+
Small changes should be indicated with revisions.
167+
These numbers don't stop at 9, so e.g. 1.11.12 is a viable number.
168+
169+
**The version number is only changed when a new release is made**
170+
171+
### Releases
172+
173+
Releases, like other changes, are made on a branch, using the following procedure:
174+
175+
1. Create a new branch.
176+
2. Update the changelog, replacing the "Unreleased" header with a version number and date, e.g. `## [0.2.0] - 2025-11-11`.
177+
3. Commit the change.
178+
4. Add a tag using e.g. `git tag v0.2.0`, and push it with `git push --tags`.
179+
5. Update the changelog, adding a new "Unreleased" header with empty categories.
180+
6. Merge the PR.
181+
7. [Add a new release](https://github.com/CardiacModelling/pcpostprocess/releases) in GitHub, using the tag you created, and copy in the changes from the changelog.
182+
183+
**TODO: THERE IS NO PACKAGING ON PYPI ATM [#105](https://github.com/CardiacModelling/pcpostprocess/issues/105)**
184+
185+
### Licensing
186+
187+
Licensing information is provided in a separate [LICENSE](./LICENSE) file.
188+

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
BSD 3-Clause License
22

3-
Copyright (c) 2024, University of Nottingham
3+
Copyright (c) 2024-2025, University of Nottingham
44

55
Redistribution and use in source and binary forms, with or without
66
modification, are permitted provided that the following conditions are met:

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,3 +111,11 @@ options:
111111
--log_level LOG_LEVEL
112112
```
113113
114+
## Contributing
115+
116+
Although `pcpostprocess` is still early in its development, we have set up guidelines for user contributions in [CONTRIBUTING.md](./CONTRIBUTING.md).
117+
118+
## Licensing
119+
120+
For licensing information, see the [LICENSE](./LICENSE) file.
121+

0 commit comments

Comments
 (0)