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 be used and currently this is the same as the release version 1.0.2. Development of slrn occurs 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 repository the source can be downloaded from John E. Davis's S-Lang Release 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 is a third party patch which may be of interest to some, either for usage or simply to see how such things are accomplished.
- Custom OS: This patch adds the ability to alter the "Operating System" section of the User-Agent header generated by slrn. It is a harmless bit of fun put together by Andrew Strong with significant guidance by Thomas Wiegner.
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 although discussion of such patches woild always be welcome on news.software.readers. And all the best with your efforts!