SipX ConfigServer Contributing
From SIPfoundry sipXecs IP PBX, The Open Source SIP PBX for Linux - Calivia
Please read SIPFoundry contributor guidelines first. This page contains additional information relevant for sipXconfig contributors.
Contents |
Developement process
sipXconfig is using a slightly modified scrum process. Many ideas about the project organization are taken from those books:
We start every month with a planning meeting. We agree on what's going to be done over the next 30 days. During the month we have daily scrum meetings - most days on #sipx IRC channel (usually at 14:30 GMT). By the end of the month we have a demo meeting during which we show what has been done and then we repeat. Those 30 days cycles are called sprints or iterations.
Every sprint has a release number associated in JIRA (3.11.5, 3.11.6 etc.) With a few minor exceptions we only tackle issues related to a single sprint. All issues are not assigned until we actually work on them. Once we start working on an issue we assign it to ourselves and put in the In Progress state. There are several useful JIRA filters that facilitate working in sipXconfig. They are all visible from a sipXconfig JIRA dashboard. Make sure you add it to your favourites.
The majority of contributions come as patches (ideally git patches) that are reviewed and committed to mainline by project coordinator. Patches and patch series are usually attached to JIRA issues. Issues with patches have to be set into Patch Submitted state.
Building sipXconfig
make vs. ant
You can use either make or ant to build sipXconfig. Most make targets is actually implemented by calling ant. Using ant gives you access to several useful targets that are not available from make (such as resting test database, running subset of tests etc.)
Tip: you can type ant -p to see the list of targets available in each directory.
You always run make targers from you BUILD directory (the directory where your Makefile files are located) and you always run ant from your source directory (the directory where your build.xml files are located).
Writing unit tests for sipXconfig
Unit tests for sipXconfig are written using the JUnit test framework. Information on JUnit is available on the project's website at http://junit.org/
There are several classes of unit tests in sipXconfig
xxxTest - Vanilla JUnit tests. These are the only tests that are run during make check phase. Present in web, neoconf, and plugins projects
xxxTestDb - Tests that require postgress database installed and running. Some of these tests use the DbUnit package to ease the burden of testing against a database. Present in neoconf project only. Please do not write any more TestDb - integration tests are faster and easier to write. The goal is to rewrite all DB tests as integration tests.
xxxTestIntegration - Similar to TestDb tests. These tests also require postgress but are much easier to write. Any tests that reference the Spring application context fall into this category. Present in neoconf project only
xxxTestUi - UI tests that require the application server (Jetty) to be running. These tests extend the JWebUnit WebTestCase class and are run within the context of a Jetty application server (using the SiteTestHelper and JetyTestSetup utility classes). Present only in web project. To run those test you need to run configure with:
JAVAC_DEBUG=on
Note on UI tests: If you are getting errors in your test about form fields that aren't found, but you have manually verified the functionality, make sure the WebTester is using the proper HTML form. By default it uses the first form on the page, which in some cases is not the form that you want. To set the form used by the WebTester, simply call tester.setWorkingForm(formName).
DB tests, integration tests and UI tests are not part of the standard make check (or ant test) targets. In order to execute all the tests you need to run:
ant test-all
Both ant and make also support 'precommit' target.
ant precommit make precommit
It cleans everything, checks style, executes all tests and installs sipXconfig. Please run 'precommit' target before submitting patches to sipXconfig and of course before committing changes to repository.
Generating patches
Patches generated by git are preferred. They are easier to apply, they correctly handle adding/deleting files. Git lets you to generate a patch series for your contribution, which helps the reviewer understand the code. Please make sure that you rebase your branch before generating patches. Git patches should have proper commit comments: see below.
sipXconfig committers follow Patch Workflow described in GIT Workflows document.
Please do not send patches with trailing spaces: they create unnecessary merge conflicts. Configure your editors to remove trailing spaces automatically (at least in Java files). Also use --check option when running git format-patches.
When submitting larger set of changes (new feature and not just a bug fix) you help reviewers by splitting the work into the logical set of steps (for example: back end changes + UI changes). On the other hand it's not polite to ask reviewer to take the series of patches that reflect the way you implemented the feature (for example: first attempt + some fixes + clean the whitespace). Please learn how use git rebase --interactive to squash and split the patches.
The proper command to generate series of patches for sipXconfig is:
git format-patch master --check git format-patch master -o <output-directory>
When attaching the patches to JIRA issue always add the comment explaining the changes. It usually should be exactly the same comment you added to the patch. If you are attaching new set of patches to the issue that already have your patches make sure to remove the original patch.
If you are attaching the patch that improves upon some other person work the polite thing to do it to generate the series on top of existing patch which allows coordinator to decide how the work should be committed. In other words if you see patches 0001 and 0002 that someone else wrote you should take them into your repo generate patch 0003 on top of it and attach it to the issue.
Commit comments
Preferred format of commit messages: make sure that you leave empty line below your commit title.
XX-nnnn short commit info Optional longer information on commit -this has been changed -that has been changed Optional information about the patch author.
Books related to tools and libraries used in sipXconfig
- Web Standards Solutions by Dan Cederholm
- Professional Java Development Spring Framework by by Rod Johnson, Juergen Hoeller, Alef Arendsen, Thomas Risberg, Colin Sampaleanu
- Java Persistence with Hibernate by Christian Bauer, Gavin King
