Space Panda

Participating in open source projects

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.


1

This applies only to Python code.

2

If this is the case, please also fix the unit test.


Tagged as git, ssh