Context Navigation

Piwik Development Process

Piwik Development Process

Piwik is an open source project. Many people contribute via ideas and patches for bugs and new features.

How we use trac for Piwik project management

We use trac to keep track of all bugs, feature requests, and other tasks concerning the Piwik software, the website, and documentation. We have a policy of keeping trac a very organized place. We make sure all tickets contain enough information: details as to how to reproduce for bugs, some sort of specification for new features, or mockups for UI improvements. We generally prioritize tickets by severity (e.g., bugs), and individual developers (Piwik team members or external contributors) decide which features they would like to implement. While we are aiming to implement the features in our roadmap, we are also open to accept new unplanned features when the code and documentation meet our quality standards.

SVN access

Piwik SVN is publicly accessible at http://dev.piwik.org/svn/

Who has SVN write access?

Developers from the Piwik team can commit in SVN:

Matthieu (matt) - Release manager
Maciej (mauser)
Anthon (vipsoft) - Issue manager
Krystian (krystian)

How can I obtain write access to SVN?

To obtain write access on the SVN server, one must be trusted by other Piwik developers. This generally means that the developer submitted a few patches in trac, implemented a new feature or improved the current code.

We are very open to welcoming new members in the team, feel free to join the fun!

How does code get committed in trunk?

All the code committed to SVN is reviewed by at least one other developer in the team. Very often, Piwik developers themselves will send bigger patches by email (or in a trac ticket) for review by another member of the team before commit - all patches submitted by external developers are extensively reviewed.

It is highly recommended that code committed in trunk/ does not break, that all unit tests pass (ran using path/to/piwik/tests/all_tests.php) and that the UI was manually tested if the user interface is affected by the change. It is recommended that the commit message references a ticket number; for example, fixes #159 - changed patch to use wrapInner() instead of wrap() will automatically close the ticket #159 in trac. You can also use the magic keyword "refs #159" and a comment will be automatically added to the ticket with a link to the changeset.

When applicable, the related online documentation and the related FAQs should be updated.

How to submit a patch?

Please make sure there is a ticket created in trac for the bug you are fixing, or the new feature you are implementing
Your code respects the Piwik coding standards and security guidelines
When applicable, the patch contains unit tests or updates existing unit tests
Make sure you have fully tested your patch
Look at an example of a simple patch
Generate your patch against the current trunk. A patch can be created using the svn command line "svn diff" or using your favorite IDE (eg. in eclipse, right click on the project > generate patch).
Submit the patch in the ticket as an attached file
Ask for review in a comment to the ticket

If the patch is non trivial, please be ready for a few iterations of this simple process: you will most likely get feedback and be kindly asked to update the code. We value high quality in the code.

When the patch is reviewed and validated by a Piwik developer, it will be committed in trunk.

To gain SVN access to the Piwik trunk, repeat this process a few times. Enjoy!

How can a third party plugin be included in core?

The adoption of a plugin into the Piwik core requires that we consider such criteria as (but not limited to):

audience - plugin appeals to a broad spectrum of users
desirabilty - is it a frequently requested feature by the Piwik community?
functionality - feature completeness
maturity - history and popularity of the plugin
performance - impact on archiving and/or UI interaction
supportability - likelihood of spawning support tickets and forum posts of the "how do I?" or "why does it?" variety
complexity - simpler is better; +1 if developer has svn commit privileges
dependencies - does it depend on closed source and/or paid subscription services?

How to submit a new documentation or new FAQ?

Submitting new documentation is very useful for users, developers, and generally a great way to contribute to Piwik

Identify the list of missing documentation or the most frequently asked questions in the forums
Experiment with the features to be documented: use the features, ask questions to the developers if necessary, identify the use cases that the feature would be used for
Submit a documentation draft in the related ticket
We will review the documentation, most likely propose some updates and make sure it covers the use cases
When the documentation is finished, it will be published on piwik.org

We also thrive to add new FAQ entries for all questions that users might ask: when a new question is asked in the forum, and if the answer would help other users, we make sure we add a new FAQ entry. This helps minimize user support as well as making users happy. To submit a new FAQ entry, please create a ticket with the question and answer, we will then review and publish it in piwik.org/faq/.

How to submit a new feature request?

When submitting a significant new feature, it is highly recommended to be as descriptive as possible when creating a ticket. The ticket should contain

a description of the product vision
a few use cases to show how useful this feature would be
mockups of what the new screens would be and how the existing screens would have to change
if applicable, examples of how the feature is implemented in other tools from the competition

Please put as much info as possible as it will help estimating the effort of the task and see how doable it would be (by the Piwik core team or a Piwik consultant). We will help with any technical details and questions outlined in the ticket.

How to submit a guest blog post?

If you have some experience in using Piwik in interesting ways - or if you simply have something interesting to share with the Piwik community, submitting a guest blog post is a great way to contribute! Here are a few guidelines for a successful blog post:

an attractive title,
a one sentence introduction explaining what the blog post is about,
some images or screenshots,
real life use cases or examples are very effective at making readers understand your message. Most likely, because you are submitting a blog post for Piwik blog, you are sharing your experience and example anyway :)
a few links to related docs or external websites - when applicable
keep it relatively short,
call to feedback / comments.

How to submit a bug?

If you believe you have found a bug in Piwik, please do the following:

make sure you are using the latest Piwik release
search in the forum, FAQ and the bug tracker if a similar or the same bug has already been reported.
if your bug seems new, do you understand how to reproduce it?
if you are ready to report a bug, register an account in the bug tracker, and create a ticket
make sure the title and description are as descriptive and clear as possible. In the bug description, please post instructions on how to reproduce, data sets that show the error if possible, screenshots, what exactly is not working? Is the issue new to you, or has it always failed? If you give a clear description, you will greatly help developers trying to reproduce and fix the issue.

Release Process

When a release is ready (when all assigned tickets to the corresponding roadmap are closed), the release is tagged with the release number (see all SVN tags).

When a release is known as being "stable", it will be tagged with the release number (for example, see tag 0.4 in SVN and the Piwik 0.4 roadmap). A shell script will then be ran by the release manager to generate the archives (zip and tar.gz) which are copied on the build server builds.piwik.org. The file builds.piwik.org/LATEST is updated with the latest stable release number. Within hours, thousands of Piwik installations will be updated via the one click upgrade mechanism - or manual upgrade - by Piwik users.

Releases that contain the string "alpha", "beta", "rc", are built for testing purposes and are not advertised on the website homepage. They are be available on the build server and the file builds.piwik.org/LATEST_BETA is updated.