How to contribute

From SpareMiNT Wiki
Jump to: navigation, search

Contents

Introduction

Contribution to any Free Software / Open Source project (where FreeMiNT is no exception) consists mainly from submitting so called "patches". This submission is generally done in some public mailing list, in our case FreeMiNT mailing list where these patches are send as attachments with some explanation what they change and why. Another (preferred) way is to create / update an issue in Bugtracker.

Patch is (usually) small text file which contains differences between your (changed) file and file in its original state. These differences are "encoded" in a special format which is understood by tools patch and diff.

Development

Before making any changes, be sure you have all Development tools correctly installed, for example by creating simple Hello World in C language. Also verify your text editor is able to handle LF line endings (TOS/DOS uses CR/LF by default) and that you've got enough space for whole source code tree on your working partition. After successful checkout or extraction of source code tree, try to build (and test!) clean sources as they are -- this will verify you're able (or not) to make full build and if the build is broken / non-working later, after adding your changes, you can be sure it's from your changes.

Development environment with Internet access

The easiest way how to create a patch is to use CVS built-in tools for this task.

  • If you are going to make some changes for the first time, you need to download current source code. Follow CVS access guide to make a checkout.
  • If you already have source code checked out, don't forget to make:
cvs update

It's important to work on current sources to minimize the risks and amount of work when committing your changes to the CVS.

  • Implement your change/bugfix (don't forget to use cvs add <file path> for new files and cvs remove <file path> for removed files!).
  • Create a patch:
cd <root directory of your project>
cvs diff -auRN > ../some_bugfix.patch

This will create patch file outside a project directory (command line options are for recursive search, unified / better readable output and for adding/removing new/deleted files). Send the patch to mailing list or submit it into bug tracker.

Development environment without Internet access

Making patches offline was typical for times before ARAnyM and network solutions like EtherNAT or EtherNEC got available for public.

  • Download source tarball. This can be done from FreeMiNT downloads or manually do cvs checkout on another machine and transfer to development machine by standard ways.
  • Implement your change/bugfix.

Submitting rules

When the feature/bugfix is done and tested, patch with description must then be submitted to the bugtracker for evaluation. If there's already an existing case in the bugtracker for the bug/feature, you add the patch as a comment in the case. If there's no case, create the case first. The patch will now be evaluated by the maintainers, and if it's found to be OK it will be applied to the current version.

Important: When fixing a bug or implementing a feature, don't change anything that's not directly related to this specific change. If you do a lot of changes at once, it will be difficult for the maintainers to evaluate your work.

Applying patch

In case you use CVS, every committed change (by someone who took your patch and committed it into source tree) is reflected in nearest cvs update. So you don't need to worry about anything. Well, except conflicts, but that's another chapter.

In case you use offline development environment, you have several options:

  • Create & compile new source tree everytime (very ineffective, as you throw all your object files away).
  • Overwrite existing source tree with new one (mostly harmless but removed files in CVS will be left on your disk as nobody will delete them).
  • Create patch by yourself and apply it with patch tool. This can be done only in case you use some other machine for CVS access, of course. You need to check what CVS revision you are in and to run cvs diff to create patch between your current revision and HEAD. Then apply this patch in your development tree with
cd <project directory>
cat <file path to your patch> | patch -p1
Personal tools
Resources