Automating the Release process using Bitergia/release-tools, Poetry, and GitHub Actions.
This work was designed and implemented for the GrimoireLab toolset. As of now, the whole workflow is supported only for Python projects. But, this can be tailored and used for any project.
This work is licensed under GPL3 or later.
This combination of the tools allows us to:
- manage your releases of your python project with proper versioning and release notes
- build the packages and test them against the test suite
- publish packages to PyPI
- Poetry should be configured to your Python project. The
pyproject.tomlfile must also be tracked on your repository. See The pyproject.toml file | Documentation | Poetry for more information. - The project should have a
_version.pyfile. This file must also be tracked on your repository. It must contain a variable named__version__. The value must be a string following semantic versioning format.
$ cat _version.py
__version__ = "3.6.5"
- The project should have
NEWSandAUTHORSfiles. - Projected should be hosted on GitHub as we use GitHub Actions.
- Once you have all the required files, you can start using the Bitergia/release-tools. The workflow is defined by the next steps:
changelog -> semverup -> notes -> publish - Developers use changelog script to generate changelog entry notes. They contain basic information about their changes in the code (e.g a new feature; a fixed bug). The notes should explain the change to a reader who has zero context about software details.
We recommend to create one of these entries for each pull request or merge request.
These notes are stored under the directoryreleases/unreleased.Example: releases/unreleased/add-sum-method.yml$ changelog -t "Add sum method" -c added Changelog entry 'add-sum-method.yml' created - Once we are ready to create a new release, we call semverup. It will increase the version according to semantic versioning and the type of changelog entries generated between releases.
$ semverup 0.1.0 - When the version is increased, we run notes to generate the release notes using the unreleased changelog entries. You can update the
AUTHORS&NEWSfiles, using the--authors&--newsflags respectively.Example: releases/0.1.0.md$ notes "calculator" 0.1.0 Release notes file '0.1.0.md' created - Finally, we publish the release in the Git repository creating a commit that will contain the new release notes and the new version files. A tag is also created with the new version number. To do it, we call to publish script. This script also removes the entries in
released/unreleaseddirectory.Example:$ publish 0.1.0 "Venu Vardhan Reddy Tekula <venuvardhanreddytekula8@gmail.com>" --push origin Cleaning directories...done Adding files to the release commit...done Creating release commit...done Publishing release in origin...done - Once the release and the tag is pushed to GitHub, GitHub Actions will be triggered and the release workflow will be initiated.
Release Workflow File: .github/workflows/release.yml
name: release on: push: tags: - '*.*.*' - '*.*.*-*' - The release workflow has 4 steps (or jobs).
build -> tests -> release -> publish - Poetry can be used to generate the wheel archives using
poetry build. Later, the distributions is uploaded to re-use in the next steps.- name: Build distributions run: | poetry build - name: Upload distribution artifacts uses: actions/upload-artifact@v2 with: name: calculator-dist path: dist - Now, we have the wheel packages ready. We would like to test the package by running the test suite. The dev-dependencies are not available in the package, so we can install it using vchrombie/peodd.
- name: Download distribution artifact uses: actions/download-artifact@v2 with: name: calculator-dist path: dist - name: Install dev dependencies run: | pip install peodd peodd -o requirements-dev.txt pip install -r requirements-dev.txt - name: Test package run: | PACKAGE_NAME=`(cd dist && ls *whl | cut -f 1 -d "-")` && echo $PACKAGE_NAME pip install --pre --find-links ./dist/ $PACKAGE_NAME pytest - The release will published on the GitHub and the release notes generated using the
notesscript will be used.- name: Get release tag id: tag run: | echo ::set-output name=tag::${GITHUB_REF#refs/tags/} - name: Create release uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ steps.tag.outputs.tag }} release_name: ${{ steps.tag.outputs.tag }} body_path: ./releases/${{ steps.tag.outputs.tag }}.md - Finally, the wheel distributions are uploaded to PyPI using Poetry. Make sure you store the
PYPI_API_TOKENwhich is needed for the authentication to upload the package.- name: Download distribution artifact uses: actions/download-artifact@v2 with: name: calculator-dist path: dist - name: Configure pypi credentials env: PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }} run: | poetry config http-basic.pypi __token__ "$PYPI_API_TOKEN" - name: Publish release to pypi run: | poetry publish - The work is currently being implemented in the GrimoireLab Repositories, after some successful trials.
- Big credit to @sduenas for the idea, work around Bitergia/release-tools and constantly helping, suggesting ideas & reviewing the work.
Licensed under GNU General Public License (GPL), version 3 or later.