pyDARN is an open source library and thus has various versions with updates. By releasing the code in versions it helps with reproducibility in publications, and allows changes to be implemented as a batch update of a version. This reduces the frequency of updates required by users to stay up to date.
pyDARN does not follow a strict release schedule because development of pyDARN is mainly driven by volunteers in the SuperDARN community.
However, if bug fixes, documentation updates, enhancements, new features, or deprecations are on the
develop branch for over a few months it is
best to make a release to get it out to the community.
One way to plan for a release associated with your work is by using milestones. In pyDARN, we use milestones for planning releases, and for organizing issues and pull requests to respective releases. This helps create a timeline for version releases.
Anyone can create a milestone on GitHub for pyDARN.
Go to pull requests on GitHub, select
milestone top right above the list of pull requests. Then select New milestone and fill in the following information:
- Title: pyDARN (See version numbers below)
- Date: due date pick something a couple months away (takes roughly 3-4 weeks of testing and getting the release branch out)
- Description: describe any specific changes focusing on for this release
Then click on Create milestone
Before creating a release issue/pull request, determine what the version type will be:
- Major: change to the user interface or large structural change to the library. Deprecations typically lead to a major release.
- Minor: new feature, enhancement or default change has been made
- Patch: bug fixes and documentation updates
Documentation doesn't need to be associated with a release unless it accompanies a new change to the code.
Then take the previous pyDARN version number and add one to the associated type location. For example, if we are on pyDARN 2.0 and:
- it's a major release then the number will be: 3.0
- it's a minor release then the number will be: 2.1
- it's a patch release then the number will be: 2.0.1
- Once a version number is determined, create an issue using the discussion template. This issue will give some heads up to testers and developers that a release will be made soon and to confirm the version number is correct. State why a release is needed and what pull requests should be included that have not been merged yet using GitHubs checklist feature
Once the pull requests needed for the releases are merged into
developthen create a release branch:
git checkout develop git checkout -b release/<version number>
Complete the Pre-Release Checklist below to make some minor changes before opening the pull request
- Now create a pull request for the release branch. This should merge into
- Add the following to the PR info:
- Title: Release pyDARN
- Scope: add information on the main focus of this release
- Include link to readthedocs on this release (DVWG Chair to do this)
- Changes: history of what has changed, look at the milestones closed tasks
- Approvals: 3 (reviews+testing)
- Testing: Using Github Checklists to include what needs to be tested, tested on what kind of data, and operating systems
- For example:
- test summary plotting
- test fan plots
- test grid plotting
- test grabbing hardware information
- test on North and South hemisphere data
- test on Borealis data
- test using RPM linux machine (OpenSuse, Fedora, RedHat)
- test using Debian linux machine (Ubuntu)
- test using MacOsX
- test using Windows
- For example:
- Title: Release pyDARN
Do this before the pull request to make it part of the review process
- Make sure the
.zenodo.jsonfile is updated to reflect the DVWG authorship guidelines and everyone is okay with the order. Please confirm with additional new members if their name and ORCID iD is correct.
version.pyfile to have the new version number on the line
README.mdfile to reflect the new changes of the release and version number
Once the test is complete and at least three approvals are obtained make sure the following steps are performed.
The pyDARN lead developer or DVWG chair should do this step; however, if you request to do it and get approval then go ahead!
- merge the release branch in
mainand confirm the above updates are there
- Tag and release the code
- tag: v
- Release Title: pyDARN v
- Description: Header "Version number - Release!" then add "pyDARN release vnumber includes the following features:" listing all the new changes to the code. Please see other releases to keep with consistency
- Hit Publish Release!
- Once a release has been made check on the pyDARN Zenodo and look for the version you just released on the right hand side under Versions. Please note this may take some time. If this does not work Contact Lead Developer and DVWG Chair on the matter.
- Once the Zenodo DOI is made for the new release, select the DOI markdown tag on the right hand side below publication date. Copy the markdown syntax.
git checkout mainand
git pull origin main
Paste this syntax in
git add docs/user/citing.md git commit -m "updated DOI links" git push origin main
Once this is done, double check everything looks correct
Uploading to PyPi
This step requires the lead developers help as they have access to the pyDARN PyPi account.
Update to make sure everything looks good:
git checkout main git fetch git pull origin main
Remove old builds
cd dist rm -rf <old versions> cd ..
python3 -m pip install --upgrade build python3 -m build
check it built the correct version
cd dist ls
python3 -m pip install --user --upgrade twine
Upload to testpypi
python3 -m twine upload --repository testpypi dist/*
you will need an account with testpypi for this to work
View the pyDARN package on the link provided in the
twine uploadoutput, should have the README.md as the front description page. If not contact pyDARN lead developer.
Check that the test page looks good and that you can download
pydarnfrom the test pypi:
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-pkg-YOUR-USERNAME-HERE
Upload to PyPi, this should be done by the pyDARN lead developer as it needs the pyDARN PyPi account:
python3 -m twine upload dist/*
Test that it worked by looking at the pyDARN PyPi page
- Install from PyPi:
pip3 install pydarnand try running pydarn
Post Release Checklist
After the above is done do the following to make sure everything is up to date:
- Let the DVWG chair know a pyDARN release has been made to update the DVWG website
- Email DARN-users about the new release of pyDARN
git checkout develop git pull origin develop git merge main