Skip to content

Commit 67e5b45

Browse files
committed
Add tasks of making a new release
* Also, move DEVELOPER_NOTES.md to folder docs.
1 parent 11728ab commit 67e5b45

File tree

1 file changed

+53
-4
lines changed

1 file changed

+53
-4
lines changed
Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,55 @@
11
## Notes for PnetCDF-python developers
2+
3+
This file contains instructions for PnetCDF-Python developers.
4+
Users of PnetCDF-Python please refer to the
5+
[PnetCDF-Python User Guide](https://pnetcdf-python.readthedocs.io/en/latest/).
6+
7+
* [Making A New Release](#making-a-new-release)
8+
* [Library Packaging And Publishing](#library-packaging-and-publishing)
9+
10+
---
11+
### Making A New Release
12+
13+
Below is a list of tasks to be done immediately before making a new release
14+
(must run in the following order).
15+
16+
1. Update the release version string
17+
* Edit file [src/pnetcdf/__init__.py](src/pnetcdf/__init__.py) and change
18+
the following string.
19+
```
20+
__version__ = "1.0.0"
21+
```
22+
23+
2. Update release note
24+
* Edit file [RELEASE_NOTES.md](RELEASE_NOTES.md) to include notes about new
25+
features and other noticeable changes.
26+
* Update the release date.
27+
28+
3. Commit all changes to github repo
29+
* Run command below to upload changes to github.com.
30+
```
31+
git push upstream main
32+
```
33+
34+
4. Create a tag and push it to the gitbub repo
35+
* Run commands below to do so. Replace the proper version string.
36+
```
37+
git tag -a v.1.0.0.pre -m "1.0.0 pre-release"
38+
git push upstream v.1.0.0.pre
39+
```
40+
5. On the browser, click [tags](https://github.com/Parallel-NetCDF/PnetCDF-Python/tags)
41+
* Click the name of tag just pushed.
42+
* Click "Create release from tag".
43+
* Fill in "Release title"
44+
* Fill in "Description field"
45+
* Optionally, click "Set as a pre-release", if this is a pre-release.
46+
* Optionally, click "Generate release notes", which will add a list of all
47+
PRs and new contributors into the Description field..
48+
* Click "Save draft" to save the changes. It can be modified later.
49+
* See all options from [github docs](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
50+
251
---
3-
### Library packaging and publishing
52+
### Library Packaging And Publishing
453
* Currently, pip-install via build distribution is disabled. No wheel files are uploaded to PyPI. Lastest pnetcdf-python package on PyPI: https://pypi.org/project/pnetcdf/
554
* Packaging: build source distribution and wheel distribution
655
1. Create virtual env and install PnetCDF-C and all python dependencies as developer installation
@@ -58,7 +107,7 @@
58107
* Pip-install command’s second go-to option if no matching build distribution is found on PyPI. It will build its own wheel file for the current system. For python libs with C-extension (like pnetcdf-python, netcdf4-python, h5py), wheel installation require their C bindings.
59108
* Invariant to platforms/versions, usually each version of python library has one single source distribution.
60109
2. Build distribution (.whl)
61-
* Pip-install command’s first go-to option by default. For python libs with C-extension (like pnetcdf-python, netcdf4-python, h5py), wheel installation does not require their C bindings.
110+
* Pip-install command’s first go-to option by default. For python libs with C-extension (like pnetcdf-python, netcdf4-python, h5py), wheel installation does not require their C bindings.
62111
* Wheels are platform-specific and python-version specific. Different system used for building and uploading will generate different versions of wheel files on PyPI. To cover most mainstream python versions and operating systems, python libraries (like [numpy 1.25](https://pypi.org/project/numpy/#files)) has 20+ wheels files to cover most mainstream systems (e.g. Linux (x86_64), macOS (x86_64), and Windows (32-bit and 64-bit)) and recent python versions.
63112
* General procedures of building and uploading python library wheels (build distributions) for MacOS and Linux systems
64113
* Python libs with C-extension (like pncpy, netcdf4-python, h5py) requires shared object (.so in linux and .dylibs in mac) files collected from C software installation. When making python library wheels (build distribution), an extra post-processing step (Delocate tool for Mac, auditwheel Tool in linux) is usually performed to copy and store these files in the python package to remove these dependencies. That’s why the user’s pip install with build distribution does not require a C installation as a prerequisite.
@@ -70,7 +119,7 @@
70119
* Developer install
71120
* Developer installation is mainly managed by `setup.py` and `pyproject.toml`. The former one is the core file to build the package and the latter manages dependencies required by `pip install` command.
72121
* `python setup.py install` builds and installs the python library based on the current python environment and will error out if dependency (e.g. mpi4py) not met. This command is going to be deprecated and is not recommended for modern python library installation.
73-
* `pip install .` works as a wrapper command for the above but it goes further: it automatically handles and install any dependencies listed in `pyproject.toml` file.Need to pay special attention to the dependencies listed in `requires` under `[build-system]` and `dependencies`.
122+
* `pip install .` works as a wrapper command for the above but it goes further: it automatically handles and install any dependencies listed in `pyproject.toml` file.Need to pay special attention to the dependencies listed in `requires` under `[build-system]` and `dependencies`.
74123
* `dependencies` defines python libraries required for running the project and will first check if requirement already satisfied in current environment before installing the latest qualified version of the library.
75124
* `requires` defines libraries required for building the project. `pip install` by default creates and uses isolated building env for building stage which completely ignores current user env. For example, if user already installed mpi4py==3.1.6, "mpi4py>=3.1.4" will still automatically install a mpi4py 4.0.0 in the building env and thereafter use syntax from 4.0.0 to build pnetcdf-python. This caused version mismatch issues between building and running envs when numpy 2.0 and mpi4py 4.0.0 are released. To address this issue, current user guide forces to use current python env for building stage by adding ` -no-build-isolation` arg to `pip install` command.
76125
@@ -86,4 +135,4 @@
86135
* Current environment variables set (only effective solution found to set env variable at installation):
87136
* `CC`: mpicc.mpich
88137
* `PNETCDF_DIR`: /home/docs/checkouts/readthedocs.org/user_builds/pnetcdf-python/checkouts/latest/_readthedocs/PnetCDF
89-
* `PNETCDF_VER`: 1.12.3
138+
* `PNETCDF_VER`: 1.12.3

0 commit comments

Comments
 (0)