Developer Responsibilities

With every freedom comes responsibilities, and if you are able to check in you also have a responsibility to contribute to the maintenance of the repository. Below is a list of the responsibilities that come with checkin access. If you cannot agree to this list, then you should not ask for checkin access.

Understand how Foswiki "works"

Read the project overview to get a high level picture of how the project functions.

Subscribe to the developer events mailing list mailing list

Subscribe to the developer events mailing list so you can follow changes in the core and standard plugins. In addition there is the #foswiki IRC channel.

Tell others what you are doing

Bugs must be reported and tracked in the Tasks web. New ideas and enhancements should be explored in the Development web, by raising a feature proposal. When common understanding and agreement is reached, the work should be broken down into individual tasks that can be added to the Tasks web.

If you want to check in code to the git repository, create a WikiGuestWouldLikeToCheckIn topic (see RequestAccessToGit), describing why you are wanting access to the repository.

Follow the checkin process

Create an Item branch for major work, new features, ...

This is the cleanest way to ensure that master is not cluttered with partially completed work.

git checkout -b Item1234
git push origin Item1234

Update before you test

You must always"git pull" before you run your pre-checkin tests, and AGAIN before you push, to ensure you are using the head of the branch. All hell will break loose if you fail to do this. It is strongly recommended that you use the --rebase option on the pull. Doing this avoids reordering commits that others have already pushed to github.

git pull --rebase && git push

And if you are running on an "Item" branch, keep it synced up with master

git pull --rebase origin master

Discuss and co-ordinate your changes with the code maintainer

Where a maintainer has been identified for the code you are changing, contact the maintainer to discuss your planned changes, and to present them for review. Also feel free to copy the foswiki-discuss mailing list to gain more feedback. For changes to the Foswiki core software components, send your notices and invitations to the foswiki-discuss mailing list.

Your final changes should be presented for review before submission. You are encouraged to offer earlier versions for review: Code inspections can often catch problems that will save you a lot of time in testing, and inspecting code prior to testing helps avoid testing that has to be thrown away due to later changes.

The maintainer co-ordinates changes between contributors, verifies that modifications are maintainable, and ensures that changes fit in with the current architecture, as well as future plans. This helps keep software components cohesive, improving its quality and flexibility.

Test your code

It may seem obvious, but has been omitted: Test your new feature or bug fix carefully. We see too many checkins where 30 minutes of plain functional testing of the new or fixed feature would have revealed very basic errors.

The github repository is a community resource that many depend on and a broken code base can block others from getting their work done. The master and release branches in git must not be used as a scratch pad for half finished code. You are asked to only check in code which is well tested and fully functioning. If you are implementing a large chunk of code then it is strongly recommended to work in an Item branch.

Run the unit tests and integration tests

There are unit tests (see test/unit/README) and integration tests (in the Testcases web). Many plugins and contribs also have unit tests. Run them - they are there for a reason. If they break as a result of your change, find out why and fix it. If the tests don't run on your platform, find out why and fix it. The unit tests are run on a regular basis by an automatic background process, which reports the results to the developer events mailing list. Make sure you monitor this list and if one of your checkins breaks the tests, fix it as soon as humanly possible, or revert the change.

Review what you have done

git status
git diff

Make sure you are not accidentally checking in any debug prints or files you didn't want to check in, and that the changes are what you expected.

Make sure that you have not forgotten to check in any new files, and that all new files are also added to the MANIFEST file.

Label your commits

When you check in, you must provide a log message describing the commit. This log message must contain the name of at least one Task that documents the change (this is known as the label). Examples:

git commit -m "Item666: changes to support slicing of bread using the power of personality"
git commit -m "Item67832: the yogurt slicer now handles peach melba correctly; Item474: peach melba added to list of supported yogurts"
git commit -m "Item2: reverted change that breaks wiki words"

Please ensure that commits have a descriptive comment that summarises the changes. Don't assume the reader has time to go and read all the Tasks you are referencing.

Document your changes

Provide documentation. This step is crucial.

• If there is existing documentation that you need to modify, do so in the version in your checkout area and commit the changes at the same time as you check in the code.
  • If you use Foswiki to edit documentation, remove any stray Ctrl-M's, and revert the TOPICINFO metadata to author="ProjectContributor" and version="1" before check-in.
• You can also write the documentation in your ChangeProposal topic, indicating where it should go. e.g: TopicCreateDateInFormattedSearch. Eventually. (The chances of documentation done this way getting merged correctly are very small; it is much better to change the Git docs.)
• Don't forget to maintain the copyright records.

Test and review at regular intervals

All changes should be tested before, and preferably after, check-in. As well as that, you should continuously monitor the health of the repository. The easiest way to do this is to use the version that is kept continuously running on the code at the head of the repository, at Tasks. Alternatively you can run your own version off the code on the git master. Even if you are not making changes yourself, other people are, and need your feedback on their changes.

If something breaks, fix it

If a change is committed that breaks the code at the head of the branch it is the responsibility of every member of the community to correct the problem. It is never someone else's problem (even if they broke it) it is always your problem.

This however does not mean that you can check in untested and maybe broken or half finished code and expect the community to fix it for you.

Revert inappropriate changes

If you submit a change that is subsequently felt by consensus to be inappropriate, or inadequate, or just plain wrong. then you are responsible for removing that change from the repository. The revision number you recorded in the ChangeProposalForm topic when you checked in can be used to isolate the changes you made. You must then revert these changes, check in again, and update the ChangeProposalForm topic describing what you did, why you did it, and the version number of the new revision.

Sometimes it will not be possible for the original author of an inappropriate change to roll it back. In this event all members of the community have a responsibility to help them out and roll back the change for them. The same process as for rolling your own changes back should be followed.

If you want/need to roll back someone else's changes because they are inappropriate, inadequate or wrong, you must try contact them first by posting in the change topic and/or by email (if possible). If you're rolling back some change because it breaks the code, you don't need to ask.

Observe the developer standards

• As with any software project, we have Coding Standards that we ask coders to follow.
• Documentation Standards help us maintain a consistent style in the reference documentation

Know how to use your tools

• git manual (and of course GitRepository)