Guidelines for Code Contributors

From OSF Wiki
Jump to: navigation, search

Introduction

Any developer can contribute code to any of the OSF projects. Depending on the project you want to contribute to, different guidelines will apply. In this guide, you will have all the resources you need in order to commit new development to these projects.

OSF is an open source framework for converting, managing, viewing and manipulating structured data. If you gain by using the framework, it is always nice to contribute back into the project. The minding of this project is Contribute as You Benefit (related to Pay as You Benefit).

Project Development Coordination

Any project development should be coordinated via the OSF Developers Community website. The community website includes this [zWiki, the OSF mailing list, the list of planned and unplanned tasks, the various lists of issues, and the various source controls.

Coding Standards

The first rule when contributing code to OSF is to follow the coding standards of the different languages used in the project. By following the standards, we make sure that there is only coding style across all the scripts of a project, which will make them easier to read and understand.

The most important part of any coding standard is the one that explains what should be documented in the code, and how. Code documentation is the best way to understand a piece of code, and to read about some background information written by the coder that won't be available only by reading the code itself. This is the most important thing to keep in mind when contributing code to any of the OSF projects.

Read more about each coding standards for each main programming language used to develop the OSF projects:

The coding standards will be enforced by Structured Dynamics if needed. But please, do as much as you can to follow them to make sure that everybody saves as much development time as possible.

Committing Code

Once new code get created in any OpenStruct projects, once it is cleaned, documented and it follows the coding standard, the next step is to commit the code in the project's source control. Depending on the project, different guidelines have to be followed. This section list each code committing guideline, for each project.

Committing Rules

Every commit you will do this any OSF project is governed by the following committing rules:

  1. Make sure your reviewed the coding standards.
  2. Properly comment your commits. Each time you perform a commit operation on the source control, you have to add a comment to this commit operation that explains what the commit is about, what it includes, what it tries to add, fix or enhance.
  3. Do as many commits as possible. Each time you fixed something, you added something or you enhanced something, commit your code to the source control. It is much easier for other people to follow and revise your work in small steps. Even if you commit a few months of work, try to split it in multiple smaller commits (each with their own comment).

Projects To Contribute To

These are the projects one can contribute to.

OSF Web Service

OSF Web Service is developed in PHP 5. The source control used to manage its code is SVN and it is hosted on Google Code. Here are some useful links to this project:

Getting Credentials to Commit

The first thing you have to do if you want to commit new code is to make sure your have the credentials to commit new code to the repository. These are the steps you have to do to get these credentials.

  1. Use an existing Google Account ID, or create a new one
  2. Create a new user on the OSF Community website
  3. Contact Frédérick Giasson, and ask him to add this Google ID to the list of possible committers. If he doesn't know who you are, he may ask you a few questions.
  4. Wait until he reply to you. Once you get credentials, you should see your ID in the "committers" section of the project page.

Once these steps are performed, you will then be able to commit new code to the source control.

Committing New Code

The branching strategy used for the OSF Web Service source control is called "stable Trunk". This means that all the development is done on one, or multiple branches. Then the trunk become the branch point where the production releases are merged.

All committers should commit new code into the dev branch. If a particular big task has to be committed, we (Structured Dynamics and the developer) could choose to create a new branch that would get merge into the dev branch.

Nothing is merged into the trunk until a new version is ready to be released. When this time come, the branch(es) are merged into the trunk. Once merged, cleaned an tested, the trunk get tagged with a release version.

Only Structured Dynamics should merge all branches into the trunk, and tag new releases.

People that want the stable versions of the project, should look to one of the tagged release version in the repository.

So, the protocol is as follow:

  1. Commit all your code in multiple commented-commits on the dev branch
  2. Structured Dynamics (and maybe others) will revise and clean the code, and will make sure it complies to the coding standards
  3. Eventually the committed code will get merged into the trunk by Structured Dynamics
  4. Once the next release is cleaned and tested on the trunk, the trunk will get tagged with a new release version

OSF-Drupal

OSF-Drupal is developed in PHP 5. The source control used to manage its code is CVS and it is hosted on Drupal. Here are some useful links to this project:

Getting Credentials to Commit

The first thing you have to do if you want to commit new code is to make sure your have the credentials to commit new code to the repository. These are the steps you have to do to get these credentials.

  1. The first step is to get a CVS account from Drupal. You have to follow the steps in this guide.
  2. Create a new user on the OSF Community website
  3. Contact Frédérick Giasson, and ask him to add accept your request. If he doesn't know who you are, he may ask you a few questions.
  4. Wait until Drupal accept your request.

Once these steps are performed, you will then be able to commit new code to the source control.

Committing New Code

The branching strategy used for the OSF-Drupal source control is that we have a development branch (DRUPAL-6--1) which is used to commit all the code from everybody. This is equivalent to the "dev branch" of the OSF Web Service SVN.

All committers should commit new code into the DRUPAL-6--1 branch.

Once a new release is ready, the dev branch will be tested, cleaned and get tagged with a new version, something like "DRUPAL-6--1-0-BETA6". It is that version that will be released on the Drupal OSF-Drupal module page, and that will be accessible for download. The development snapshot available from the module page is not mean to be a stable release, and one should expect issues if they try to use it

Only Structured Dynamics should create new version tags from the dev branch

People that want the stable versions of the project, should look to one of the tagged release version in the repository.

So, the protocol is as follow:

  1. Commit all your code in multiple commented-commits on the DRUPAL-6--1 branch (which is referred by Drupal as the dev branch)
  2. Structured Dynamics (and maybe others) will revise and clean the code, and will make sure it complies to the coding standards
  3. Eventually the commit ed code will get merged into the trunk by Structured Dynamics
  4. Once the next release is cleaned and tested on the trunk, the trunk will get tagged with a new release version

Semantic Components Library

The Semantic Components Library is developed in Action Script 3. The source control used to manage its code is SVN and it is hosted on Google Code. Here are some useful links to this project:

Getting Credentials to Commit

The first thing you have to do if you want to commit new code is to make sure your have the credentials to commit new code to the repository. These are the steps you have to do to get these credentials.

  1. Use an existing Google Account ID, or create a new one
  2. Create a new user on the OSF Community website
  3. Contact Frédérick Giasson, and ask him to add this Google ID to the list of possible committers. If he doesn't know who you are, he may ask you a few questions.
  4. Wait until he reply to you. Once you get credentials, you should see your ID in the "committers" section of the project page.

Once these steps are performed, you will then be able to commit new code to the source control.

Committing New Code

The branching strategy used for the Semantic Components Library source control is called "stable Trunk". This means that all the development is done on one, or multiple branches. Then the trunk become the branch point where the production releases are merged.

All committers should commit new code into the dev branch. If a particular big task has to be committed, we (Structured Dynamics and the developer) could choose to create a new branch that would get merge into the dev branch.

Nothing is merged into the trunk until a new version is ready to be released. When this time come, the branch(es) are merged into the trunk. Once merged, cleaned an tested, the trunk get tagged with a release version.

Only Structured Dynamics should merge all branches into the trunk, and tag new releases.

People that want the stable versions of the project, should look to one of the tagged release version in the repository.

So, the protocol is as follow:

  1. Commit all your code in multiple commented-commits on the dev branch
  2. Structured Dynamics (and maybe others) will revise and clean the code, and will make sure it complies to the coding standards
  3. Eventually the committed code will get merged into the trunk by Structured Dynamics
  4. Once the next release is cleaned and tested on the trunk, the trunk will get tagged with a new release version

irON Parsers

irON Parsers are developed in PHP 5. The source control used to manage its code is SVN and it is hosted on Google Code. Here are some useful links to this project:

Getting Credentials to Commit

The first thing you have to do if you want to commit new code is to make sure your have the credentials to commit new code to the repository. These are the steps you have to do to get these credentials.

  1. Use an existing Google Account ID, or create a new one
  2. Create a new user on the OSF Community website
  3. Contact Frédérick Giasson, and ask him to add this Google ID to the list of possible committers. If he doesn't know who you are, he may ask you a few questions.
  4. Wait until he reply to you. Once you get credentials, you should see your ID in the "committers" section of the project page.

Once these steps are performed, you will then be able to commit new code to the source control.

Committing New Code

The branching strategy used for the irON Parsers source control is called "stable Trunk". This means that all the development is done on one, or multiple branches. Then the trunk become the branch point where the production releases are merged.

All committers should commit new code into the dev branch. If a particular big task has to be committed, we (Structured Dynamics and the developer) could choose to create a new branch that would get merge into the dev branch.

Nothing is merged into the trunk until a new version is ready to be released. When this time come, the branch(es) are merged into the trunk. Once merged, cleaned an tested, the trunk get tagged with a release version.

Only Structured Dynamics should merge all branches into the trunk, and tag new releases.

People that want the stable versions of the project, should look to one of the tagged release version in the repository.

So, the protocol is as follow:

  1. Commit all your code in multiple commented-commits on the dev branch
  2. Structured Dynamics (and maybe others) will revise and clean the code, and will make sure it complies to the coding standards
  3. Eventually the committed code will get merged into the trunk by Structured Dynamics
  4. Once the next release is cleaned and tested on the trunk, the trunk will get tagged with a new release version

Publication of your Contributions

Once your work has been committed to one of the source control, you should then write a mail that you will send to the OSF mailing list so that you publish the result of your work. Once this is done, other people will be able to revise and fix it if necessary. Also, Structured Dynamics will revise any piece of code that is committed to any of the stores in order to make sure that it complies to this guideline.

Eventually, your code will make it to the next release of the project, and will be moved from the development branch of the source control to the trunk. Then, at the time of the new release, code documentation will be generated from your code, and will appear in the Code Documentation of the project you contributed to.