Contributing to Damus!

You can use github PRs to submit code but it is not encouraged. Damus is a decentralized social media protocol and we prefer to use decentralized techniques during the code submission process.

[Email patches][git-send-email] to patches@damus.io are preferred, but we accept PRs on GitHub as well. Patches sent via email may include a bolt11 lightning invoice, choosing the price you think the patch is worth, and we will pay it once the patch is accepted and if I think the price isn't unreasonable. You can also send an any-amount invoice and I will pay what I think it's worth if you prefer not to choose. You can include the bolt11 in the commit body or email so that it can be paid once it is applied.

Recommended settings when submitting code via email:

$ git config sendemail.to "patches@damus.io"
$ git config format.subjectPrefix "PATCH damus"
$ git config format.signOff yes

You can subscribe to the [patches mailing list][patches-ml] to help review code.

Submitting patches

Most of this comes from the linux kernel guidelines for submitting patches, we follow many of the same guidelines. These are very important! If you want your code to be accepted, please read this carefully

Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that motivated you to do this work. Convince the reviewer that there is a problem worth fixing and that it makes sense for them to read past the first paragraph.

Once the problem is established, describe what you are actually doing about it in technical detail. It's important to describe the change in plain English for the reviewer to verify that the code is behaving as you intend it to.

The maintainer will thank you if you write your patch description in a form which can be easily pulled into Damus's source code tree.

Solve only one problem per patch. If your description starts to get long, that's a sign that you probably need to split up your patch. See the dedicated Separate your changes section because this is very important.

When you submit or resubmit a patch or patch series, include the complete patch description and justification for it (-v2,v3,vn... option on git-send-email). Don't just say that this is version N of the patch (series). Don't expect the reviewer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. This benefits both the maintainers and reviewers. Some reviewers probably didn't even receive earlier versions of the patch.

Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour.

If your patch fixes a bug, use the 'Closes:' tag with a URL referencing the report in the mailing list archives or a public bug tracker. For example:

Closes: https://github.com/damus-io/damus/issues/1234

Some bug trackers have the ability to close issues automatically when a commit with such a tag is applied. Some bots monitoring mailing lists can also track such tags and take certain actions. Private bug trackers and invalid URLs are forbidden.

If your patch fixes a bug in a specific commit, e.g. you found an issue using git bisect, please use the 'Fixes:' tag with the first 12 characters of the SHA-1 ID, and the one line summary. Do not split the tag across multiple lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify parsing scripts. For example::

Fixes: 54a4f0239f2e ("Fix crash in navigation")

The following git config settings can be used to add a pretty format for outputting the above style in the git log or git show commands::

[core]
	abbrev = 12
[pretty]
	fixes = Fixes: %h (\"%s\")

An example call::

$ git log -1 --pretty=fixes 54a4f0239f2e
Fixes: 54a4f0239f2e ("Fix crash in navigation")

Separate your changes

Separate each logical change into a separate patch.

For example, if your changes include both bug fixes and performance enhancements for a particular feature, separate those changes into two or more patches. If your changes include an API update, and a new feature which uses that new API, separate those into two patches.

On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch.

The point to remember is that each patch should make an easily understood change that can be verified by reviewers. Each patch should be justifiable on its own merits.

If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description.

When dividing your change into a series of patches, take special care to ensure that the Damus builds and runs properly after each patch in the series. Developers using git bisect to track down a problem can end up splitting your patch series at any point; they will not thank you if you introduce bugs in the middle.

If you cannot condense your patch set into a smaller set of patches, then only post say 15 or so at a time and wait for review and integration.