Development Process

The ForgeRock Development Process is built on agile practices and adheres to the ForgeRock Development Principles. This process is used for all community projects in the ForgeRock I3 Open Platform.

Overview of the Development Process

There are a few guiding principles for general development process. Strive to keep trunk in a buildable state. This means that if there are significant changes that will affect multiple files or areas of the product, they should be developed in isolation (discrete branch) until you are comfortable that they will not break the build. Once they are complete, they can then be merged into the trunk. Be aware of compatibility - backward and forward. Any API level changes should be brought to the band. Dont re-invent the wheel! The products use many libraries, and implement many useful utility methods. Re-use them. We will use version control. Currently the projects use SubVersion, however this is subject to change at any time. Do not build assumptions around the specific version control system in use into the project. process

The Development Context

Testing

The amount of testing for each bug fix or RFE should be determined by the dev and QA team. The general guideline is that all unit tests should be run for any fix.

How to commit

In order to submit changes to the OpenAM source tree, one has to be at least a Fan. This means that they have to have a login into forgerock.org. There are 3 different kinds of code submissions that we need to address:
  1. Simple patches to trunk
  2. Complex patches to trunk
  3. Extensions

Simple Patches to trunk

Simple patches to the main trunk, are patches that affect less than 100 lines of code, and affect less than 5 physical files. This is expected to be the majority of fixes for issues raised in Jira. Most fixes are going to be 3 or 4 lines. After review the patch is committed directly to the trunk.

Complex Patches to trunk

Complex patches to the main trunk, are patches that affect more than 100 lines of code, affect more than 5 physical files or is being developed by more than one developer. This kind of patch has to be developed in its own branch, allowing the developers to commit changes and test changes. Any contributor can request a branch for their development. Branches are expected to be transient and to only be valid for the length of the development of that feature or fix. Once the development work is completed, it will be merged back into the trunk.

Extensions

Extensions are meant for longer term projects, or sub-projects that are not supported by Forgerock. Any Contributor can request an extension, over which they have control. The Band will determine if this is a reasonable sub-project and will not unreasonably withhold approval. The extension owner is able to determine who will have developer access and how they will handle commits. At some point, an extension might be mature enough to be brought into the supported software, at which time, it will become part of the main OpenAM project and subject to the normal submission process.

Submitting code changes

The way that you contribute code changes depends on what kind of user you are. A fan always has to submit changes as a "review then commit". A roadie or rockstar is able to submit changes using either "review then commit" OR "commit then review".

Review then Commit

The development process for a simple patch is:

  1. Check out the latest version of the trunk to a local workspace.
  2. Edit your local files making the changes you deem necessary.
  3. Build and verify your changes.
  4. If there has been a significant time since you checked out the source, you might want to sync up, and verify your fix still works
  5. Generate a diff using svndiff.
  6. In Crucible; create a review request and paste your diff.
  7. Once your patch has been reviewed a Roadie or Rockstar will commit the patch to the trunk.

The development process for a complex patch is:

  1. A branch will be created for your fixes. You will have full commit access to the branch
  2. Check out the latest version of the branch to a local workspace.
  3. Edit your local files making the changes you deem necessary.
  4. Build and verify your changes.
  5. Commit your changes into your branch.
  6. If there has been a significant time since the branch was created, you might want to sync up with the trunk, and verify your fix still works
  7. In Crucible; create a review request, based on your branch and the trunk.
  8. Once your patch has been reviewed a Roadie or Rockstar will merge and commit the branch into the trunk.

Commit then Review

The Commit then Review process is meant to be used by Roadies or Rockstars, when making simple changes that they are confident will not adversely affect main source. It is always a good idea to have someone else review any changes before committing them and “review then commit” is the suggested method for any non-trivial changes. The development process for a simple patch is:

  1. Check out the latest version of the trunk to a local workspace.
  2. Edit your local files making the changes you deem necessary.
  3. Build and verify your changes.
  4. If there has been a significant time since you checked out the source, you might want to sync up, and verify your fix still works
  5. Commit your changes back into the trunk.
  6. In Crucible; create a review request, based on the your changes.
  7. Once your patch has been reviewed and not accepted a Roadie or Rockstar will remove the patch from the trunk.

Bug fixes/minor RFE's

A bug fix or a very minor request for enhancement (RFE) should not have a big overhead. The prerequisite is that the resulting functionality in the product is not significantly altered by the change. This eliminates a lot of the work in considering the impact of larger changes. The development process for a bug fix or minor RFE is as follows:

  1. An issue representing the bug/RFE is created in the JIRA project for the product
  2. Issues are prioritized by the project lead and assigned to a developer. Alternately, community developers are free to fix any bug they wish although inclusion in the next build cannot be guaranteed.
  3. The developer analyzes the bug and updates JIRA. If a minor RFE will change functionality more than expected then the issue should be upgraded to a major RFE and follow the appropriate development process.
  4. The developer creates a branch in subversion, the version control system that ForgeRock use, and fixes the issue. All code changes should be made in the branch.
  5. The developer commits the code fix and unit tests, and includes the JIRA issue number in the subversion commit message. This causes the commit and the files changed to appear automagically in the JIRA issue. Commits without a JIRA issue or unit test will be challenged by the project lead.
  6. The developer changes the status of the JIRA issue to "Resolved" and assigns to the project lead.
  7. The project lead initiates a code review using Crucible/Fisheye
  8. The reviewers complete the review. If any changes are necessary then they are handled during the review or the issue is reopened.
  9. The issue is assigned to a developer with commit rights to the trunk, the code is merged with the trunk.

Note that branches in subversion are "cheap" and do not create a copy of code until the files are changed.