Contributing to Prosody

Prosody is a collaborative and open project, and we welcome contributions. This page describes the steps to submit your first patch.

Will my patch be accepted?

Generally we accept all patches, but some things to note:

  • The quality and size of our codebase is very important to us. We prefer smaller patches that implement fixes and features as simply as possible.
  • If your feature can be implemented as a plugin instead of a patch to Prosody's core code, do that. We often remove even our own features from Prosody if we feel they don't deserve to be there!
  • Prosody is used in some high-load environments, and in general it's important that it performs well (but not usually at the expense of the things listed above).
  • Submit one patch per feature/improvement. This makes it easier for us to review.

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.

Using Mercurial

Prosody uses Mercurial (hg) for its source repository. If you aren't familiar with it, don't worry - it is very easy to use.

Cloning the Prosody repository

After installing Mercurial, get a copy of Prosody's source repository with:

  hg clone https://hg.prosody.im/trunk prosody-trunk

Setting your identity

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 <john.smith@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).

Making changes

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).

  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.

Preparing the changes for submission

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:

  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.

Submitting changes

Select the best way to submit your changes:

  • The chatroom, if it is the current topic of discussion
  • Via email to developers@prosody.im (include the words 'prosody' and 'patch' in the subject line)
 
doc/contribute.txt · Last modified: 2016/08/03 19:51 by Kim Alvefur