How to create and use patches with slrn
John E. Davis and the slrn community welcome well-tested patches that can be applied against the development version of slrn. This page describes how to access this source code from the slrn git repository, demonstrates a few patches already in circulation and gives a few simple guidelines to follow to enable your patch to meet a warm reception from the slrn community.
Getting the slrn "development" source code
To produce patches for the slrn source code it is strongly advised that the "development" version of slrn, known as pre1.0.0 is used. It is held in a git repository hosted by John E. Davis. To access this source code you will need to install a suitable git client and then issue the following command:
$ git clone git://git.jedsoft.org/git/slrn.git
This will download a copy of the most recent version of slrn into a directory called slrn and from there it can be compiled and installed as normal. Besides the obvious need for compiling software slrn requires S-Lang and its "development" files to be installed before compiling slrn. If this is not available from your distribution it can be downloaded from JED's S-Lang Library Information Page.
This code is easy to update by simply using the command
git pull and it is this code that should be used to produce patches especially if you wish your work to be included in the slrn source code of future "release" versions. Some examples of patches are included below.
Some existing patches for slrn
Below are some samples of patches that have been written by third parties, they have been tested against the older subversion slrn and are not currently included in the source code. Importantly these patches have for the most part have not been tested against the current development version held in JED's git repository. (Details of the old subversion repository can still be found here.)
- Score Color Patch: This patch by Rudy Taraschi is an enhancement to slrn that allows you to assign different colors to arbitrary score ranges. It has been running solidly for about four years and is described in some detail on his web site.
If there are more quality patches for the git slrn that you feel could be shown on this page please contact the slrn-users list and mention this page.
Some general guidelines for producing slrn patches
Below are a few very general guidelines for producing patches that will be submitted for possible inclusion into the slrn source code. These are basic guides that are drawn directly from the svn mplayer guidelines and from notes made by Thomas Schultz:
- Do not send complete files. These need to be diffed by hand to see the changes which makes reviews harder.
- Use the most current git version of slrn for your patch.
- Use the same naming schemes and indentation as the official slrn sourcecode.
- Make unified diffs, unified diffs can be applied easily with 'patch'. This is much harder with other diff types. Besides, unified diffs are more readable and thus easier to review.
- Create the diff from the root of the slrn source tree, this makes the diff easier to apply as it saves the step of searching for and changing to the correct directory.
- Include documentation for your changes. Try to provide a good description that can be included in the new manual. Color objects and key bindings should also be added to the sample
- Comment parts of your code that really need it.
When your patch has been tested and ready for submission I would suggest that the best place for submission would be the slrn-users list. And all the best with your efforts!