Every now and then open source projects are not on any of the popular platforms, but you'd still like to participate by contributing code, report bugs, or ask for new features.
Here's how you can contribute to the code base of projects that are living over at vonshednob.cc.
Get the source code
Signed Releases
All releases on vonshednob are signed with the releases OpenPGP key. You can download it at vonshednob.cc/pgp/releases.asc.
The quickest way to import through the commandline:
curl 'https://vonshednob.cc/pgp/releases.asc' | gpg --import
You can get the source code either directly from vonshednob.cc or from the respective project page on PyPi 1.
Let's assume you want to do something to the code of pytodotxt. Here’s how you can download version 1.2.1:
# get the source code wget 'https://vonshednob.cc/releases/pytodotxt-1.2.1.tar.gz' # get the signature wget 'https://vonshednob.cc/releases/pytodotxt-1.2.1.tar.gz.sig' # verify the download gpg --verify pytodotxt-1.2.1.tar.gz.sig
Don't skip the verification part! The output should look similar to this:
gpg: assuming signed data in 'pytodotxt-1.2.1.tar.gz' gpg: Signature made Fri 28 Jan 2022 02:44:06 PM UTC gpg: using RSA key 4EE66E48280C80C7D96E5C7C50D884C0AC00A05D gpg: issuer "releases@vonshednob.cc" gpg: Good signature from "releases@vonshednob.cc" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 91E7 EDB3 9BBA 4673 D9FC FBC4 2E04 CB76 0B9C 370A Subkey fingerprint: 4EE6 6E48 280C 80C7 D96E 5C7C 50D8 84C0 AC00 A05D
The important part is the Good signature from
bit, indicating that this
public key can verify the signature for that file.
The WARNING
is there to tell you that you have not assigned any sort of
trust to this key, which is understandable: you just downloaded it from the
internet. Maybe even at the same location from where you got the package
itself.
Create a local git repository
To start working on the source code, you should create a git repository to track any and all changes that you have made:
# extract the code tar xf pytodotxt-1.2.1.tar.gz # create a new git repo in it and initialize it cd pytodotxt-1.2.1 git init . git add . git commit -m 'init'
Make the changes you want to see in this world
Now you can start making changes. It doesn’t matter what branch you choose to make changes in, the repository is standing on its own.
Once you implemented the feature(s) that you wanted to see or fixed the bugs that annoyed you to no end, please remember to update these:
CHANGELOG.md
, with a summary of the changes/additions you provided
AUTHORS.md
, if you want to be listed as an author in this project
tests/
, maybe you added unit tests for the changed or added functionality
doc/
, please update the user handbook, if there's something new or if existing functionality changed
Generate and email the patch file
Once you're happy with all the changes, didn't break any of the existing unit tests (unless that was part of the needed change 2), you can wrap up your changes into a patch file:
# produce the diff git diff `git rev-list HEAD | tail -n 1` HEAD > pytodotxt.patch
This is a very blunt approach to create a diff from all changes since the creation of the repository.
If your repository has lived for a long time already and contains multiple patches already, it’s a good idea to create a diff containing only the new changes that you want to send out.
Now it’s time to send the patch file to the maintainer of the software. For
projects at vonshednob.cc, you can find the contact email address inside
the package (for example in the setup.py
).
Thank you
Pretty much every contribution to open source projects is welcome — from feature requests to bug reports and code changes.
So, thank you for reading this and for considering to help!
Bonus
If you set up your sendemail
options, you can use git send-email -1
HEAD
to send a patch right there from the command line.
Have a look for the git send-email man page for more details.