2016/05/18 - Apache Continuum has been retired.

Creating and submitting a patch

When you have either completed an issue or just want some feedback on the work you have done, create a patch and attach the patch to the issue in question. We have a couple of guidelines when creating patches:

• Always create the patch from the root of the continuum project, i.e. where the pom.xml file is.
• If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.
• Name the file CONTINUUM-<issue number>-<artifact id>.patch.
• Attach the patch to the JIRA issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.

An example on how to create a patch from the command line:

$ svn diff > CONTINUUM-1234.patch

If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The wget and patch commands will only be available if you are on a UNIX platform or using Cygwin on Windows.

$ wget -O - -q <URL to the patch from JIRA> | patch -p0

If the patch is in a local file CONTINUUM-1234.patch and you want to apply that use this command:

$ patch -p0 < CONTINUUM-1234.patch

A couple of notes:

• If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make it difficult for us to apply as we most likely don't have the same directory structure as you.
• Make sure that you follow the code style.

Other useful Subversion commands while developing

If you've done a chunk of work and you would like ditch your changes and start from scratch use this command to revert to the original checkout:

$ svn revert -R .

The -R argument means that the command will recurse down all directories and revert all changes.

Before committing code to the Subversion repository we always set the svn:ignore property on the directory to prevent some files and directories to be checked in. We always exclude the IDE project files and the target/ directory. Instead of keeping all of the excludes in mind all the time it's useful to put them all in a file and reference the file with the -F option:

$ svn propset svn:ignore -F ~/bin/svnignore .

An example svnignore file:

target
*~
*.log
.classpath
.project
*.ipr
*.iws
*.iml

Patch acceptance criteria

There are a number of criteria that a patch will be judged on:

• Whether it works and does what is intended. This one is probably obvious!
• Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.
• Whether it contains tests. It is expected that any patches will be accompanied by unit tests and/or integration tests. If you're not sure how to write a test for your change, please ask for help on the dev list. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.
• Whether it contains documentation. All functionality needs to be documented for users and developers, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.

  Above all, don't be discouraged. These are the same requirements the current committers should hold each other to as well. And remember, your contributions are always welcome!

Commit Message Template

Commits should have a message that follows this template:

[issue] <<summary>>
<<description>>
Submitted by: <<name>>

[issue] can be omitted if there is no relevant JIRA issue, though it is strongly encouraged to create one for any non-trivial change.

summary should briefly describe the problem or intent. Often the summary from the JIRA issue will work.

description should describe what was changed, and why. This is important so that others can follow your thought process and evaluate the change.

Submitted by only needs to be included when a patch is being applied for a non-committer.

For example:

[CONTINUUM-1234] Fix X when doing Y
Added a check to make sure Z is true before we decide to... This will prevent...
Submitted by: Baz Bazman