Prosody is a collaborative and open project, and we welcome contributions. This page describes the steps to submit your first patch.
Generally we accept all patches, but some things to note:
If you need help converting a patch to a plugin, let us know - we may have ideas about how best to achieve it.
In general, always talk to us first before you put a lot of work into anything. It's quite possible we already have ideas, plans, or have even started work on it ourselves. The chatroom is the best place to discuss contributions.
Prosody uses Mercurial (hg) for its source repository. If you aren't familiar with it, don't worry - it is very easy to use.
After installing Mercurial, get a copy of Prosody's source repository with:
hg clone https://hg.prosody.im/trunk prosody-trunk
Now, before you go any further, tell Mercurial a little bit about yourself. This will be your identity attached to commits you make.
Open up ~/.hgrc in a text editor, create the file if it doesn't exist (see
hg help config if you need more info on this).
You want two lines like this in the file:
[ui] username = John Smith <email@example.com>
This name and email address will be public on all commits. We encourage you to use your real name if you will, but we won't be bothered if you don't. Your email address should be valid and working, and one that you are comfortable with being publicly visible (we do our best to obfuscate addresses from spam harvesters).
Make your changes in the prosody-trunk directory created in the first step. When you are ready, and have tested them locally, you are ready to commit them.
If you would like review before you do so, feel free to paste the output of
hg diff in the Prosody chatroom for feedback.
To commit your changes, use the
hg commit command (often shortened to
hg ci FILE1 FILE2...
If you specify any files, hg will only commit those - if you specify none, it will commit all changes in the repository at once. Generally try to make commits as small as possible. Fix one bug, or add one feature, per commit.
Mercurial will prompt you for a commit message. Prosody commit messages follow a standard format:
mod_foobar: Twiddle the whatsits to allow seamless reloads, fixes #62
The message begins with the names of the module(s) that it modifies, followed by a description of what the change does. We generally don't do lengthy commit messages, because the commit should already be small enough to see what it does - a short description should be enough. Be sure to mention any bugs that it fixes.
Now for the final part. The best format for your submission depends mainly on how many commits you are sending. To quickly submit the last thing you committed, run:
hg export tip > prosody-issue62.patch
If you can, name the patch something better than 'prosody.patch'. You have no idea how many files I have with that name already. Anything short and descriptive will do, a bug number is excellent if you have one.
If you have multiple commits to send, the best way is via
hg bundle prosody-issue62.hg
This will automatically put all commits from your repository that are not in Prosody's repository into a (binary) file. Simply send us this file, and we can pull the changes from it.