Contributing¶
How to contribute to the carbon-txt validator project¶
The Carbon.txt validator is an open source project and contributions are welcome.
Our issue tracker is on Github, and maintain a high level roadmap of coming releases as milestones.
Getting set up¶
Follow the instructions in installation to get set up if you are on a local machine.
If you prefer to use remote workspace - see this issue for setting up a Github Codespace, (contributions welcome!)
Publishing a release¶
To publish a release to PyPi, on the branch you want to release, you need to create a tag matching the version number in pyproject.toml, and then push that tag to the main repository.
If you have origin set to this repository like so:
# output from git remote -v
origin git@github.com:thegreenwebfoundation/carbon-txt-validator.git (fetch)
origin git@github.com:thegreenwebfoundation/carbon-txt-validator.git (push)
And you wanted to push tag 1.2.3, first check that your pyproject.toml has that release number:
# pyproject.toml
[project]
name = "carbon-txt"
version = "1.2.3"
Then make a git tag, making sure you have the v prefix for the version number:
git tag v1.2.3
There is a Github action set up in .github/workflows/release.yml that listens for new tags being pushed to the main repository. When a new tag is pushed to the repository, the action builds the python package, and then pushes the release to PyPi using the Trusted publisher process.
To push a git tag, use the tag name when pushing to the origin repository. In our case of creating tag v1.2.3 we push tag v1.2.3 to origin:
git push origin v1.2.3
What happens after I push a tag?¶
It’s worth reviewing the Github action source directly as the final source of truth, but in the nutshell, the Github action responsible for creating releases does the following:
Checkout that specific tag from the git source repository
Install dependencies for building the python package
Build the package, checking that the git tag and the python release version match
Publish to the main PyPi package repository
Assuming the action has successfully run, your release should be visible on PyPi at https://pypi.org/project/carbon-txt.
If your release version was 1.2.3, it would be available at https://pypi.org/project/carbon-txt/1.2.3/
Deleting a tag¶
Tags are tied to specific commits, not branches. So if you have created a tag for a release but have not pushed it, you can delete the tag, locally like so:
git tag -d v1.2.3
You can then re-tag the relevant commit, ready to push and publish:
git tag v1.2.3
git push origin v1.2.3
Once a tag has been pushed to Github, and used in the publishing workflow, you will not be able to re-use it. See the steps below to avoid ‘wasting’ a tag.
If you’re not sure about pushing a release yet¶
This project broadly follows Semantic versioning.as defined on the Python Packaging website page on versioning.
If you want to test the package with others first
If you want to test out publishing a release on the main PyPi site, use a release candidate suffix, (i.e. v1.2.3rc1) with your tags and versions.
If you want to test the release process itself to get comfortable with it
Use the PyPi test site. Can deploy to the test PyPi site by setting up a .pypirc file in your home directory and adding inside that file tokens issued on the test.pypi.org website.
# ~/.pypirc
[pypi]
username = __token__
password = pypi-LONGPASSWORD
[testpypi]
username = __token__
password = pypi-LONGPASSWORD
You can then trigger an upload manually using the twine library :
uv run twine upload --repository testpypi dist/* --verbose
Assuming you have set up Trusted Publishing on test.pypi.org you can try a test publish by adjusting the Publish to PyPi Github action in release.yml like so:
- name: Publish package distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
# this bit switches where the "Publish to PyPi" action
# publishes to
with:
repository-url: https://test.pypi.org/legacy
Using a just task to manually upload builds¶
If you prefer, there is also a handy just task for publishing the carbon-txt-validator from a local machine. Run just publish to build and upload the latest release to PyPi:
just publish
Seeing and building documentation¶
The documentation for this project are built using Sphinx, using the myst_parser to support Markdown, and the furo theme.
Updating the documentation locally¶
You can build docs once using just docs to generate the docs, placing the generated html in ./docs/_build/_html.
If you’re working on the docs, it’s helpful to see them update as you work.
Use the just docs-watch command to start a live-updating server, by default listening at http://127.0.0.1:8000.
As you make changes to the documentation source files, the rendered results will show in your browser.
Updating the public documentation¶
Every time changes are merged into the main branch, a build script at Read the docs generates the documentation to serve at the URL below: