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 Open Identity Stack.

Any questions, comments or feedback to the ForgeRock community team can be emailed to community@forgerock.com

Development Guidelines

There are a few guiding principles for general development process.

  • The trunk is sacred. It does NOT break.
    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.
  • Use the one pager process to get early requirements and design feedback for enhancement or complex fixes.
    The One pagers give everyone a chance to see what you are working on, and to be involved in the design process
  • Remember many people depend on the project.
    Keep people informed of things that have impact
  • Be aware of compatibility – backward and forward.
    Any API level changes should be brought to the band.
  • Don’t re-invent the wheel!
    The products use many libraries, and implement many useful utility methods. Re-use them.
  • Communicate – Communicate – Communicate!
    Tell people what you are doing, ask for help, ask for advice. Questions are good. Remember: Communicate!

Copyright & License

No matter what you contribute, there are going to be copyright and license issues we have to address.

There are only two kinds of contributions you are able to contribute:

  1. Work that you have personally done yourself, for which YOU are the copyright holder
  2. Work that you have EXPLICITLY been given license to contribute.

Any contribution you make will always be under license. You can also assign the copyright if you wish.

There are many different open source licenses all of which grant the licensee different rights. Forgerock.org uses the CDDL, although many licenses are compatible, we cannot accept other licenses without explicit approval from the community manager. We are unable to accept any code, (or dependencies on) that is licensed under GPL.

Please contact community@forgerock.com if there are any questions around this, as it can be a complex, and sticky topic.

If your contribution consists of multiple files, having a file as part of the submission that lists all dependencies, and licenses under which they are used, would make it much easier to verify.

Every source file should have a comment near the top, (suitable form for the content). The contents of the comment should be as is shown in the section in licenses. For more detail, see the section on Licenses.

Now, on to contributing:

Project Contributions

There are several ways you can contribute to the projects, and several types of contributions.

Wiki Contributions

As a community member, you are automatically able to contribute articles to the wiki, or update articles that are already there. Remember, if it took you a little time to work something out, It is likely to take others as well! It might seem small, or simple once you work it out, but sharing your experiences is often very helpful to other members. Any help you get from the articles, has come from others who have contributed their experience, so you are encouraged to jump on it.

No special instructions to contribute, just get started.

https://wikis.forgerock.org/confluence/display/openam/Wiki+Contribution+Info

Documentation

We encourage those who wish to more formally contribute to the documentation (admin guide, or install guide, etc.).  Contact us at community@forgerock.com. The process will be similar to the code contribution process, described below.

Internationalization

Speak more than one language? If you would like to contribute localizations and translations, contact us.

Code contributions

There are three ways to get involved with code contributions. All follow exactly the same process. These are:

Patch submission to JIRA

This is by far the easiest and simplest way to participate in the development process. Any community registered member can comment, and work on a JIRA issue. A patch can be uploaded and it will be worked as part of the standard development cycle.

Extension or Branch submission to JIRA

This is very similar to submitting a patch, except you can work as an extension. This is useful if your contribution is a significant size, or complexity that it takes a lot of time to write. Since this typically is a lot of code, it makes a lot of sense to work closely with the development team to ensure that your contribution is understood, and is manageable from a code review perspective.

Work on bi-weekly sprints with the dev team

For those who are approved, we have the ability for our community members to become part of the dev team.  If you want to be part of the dev team, you would need to commit to attending the daily standup meetings, and participating in the bi-weekly sprints. You would be treated as part of the sprint, and expected to fulfill any commitments you make to the sprint.

No matter how you contribute, the process is the same

With every contribution, Everything starts with JIRA, the issue tracker. The first step in doing anything, is to create a JIRA issue that explains, and defines the issue that is going to be addressed. Issues are identified as either a bug, or a new feature. We are not using the “improvement” as an issue type. When you create your issue, you should include sufficient details in the comments section so that anyone else reading your issue can quickly understand what the issue is about. See the section about creating JIRA Issues.

JIRA tasks are created by contributors who are going to be actively working on an issue. Tasks are used to describe specific work items that need to be done. Often an issue might have a documentation sub-task, or a testing subtask, as those needs are identified. If the issue is fairly major in scope, it might be broken down into smaller engineering subtasks as well, allowing different aspects to be worked on by different engineers. Once you have completed the task, you can mark the task as resolved. A Task is generally closed by the project lead, and only after it has been tested. See the section on JIRA Tasks.

Once you have identified a JIRA issue to work on, you can either assign it to yourself, or if you are unable to assign it, you can contact the community manager, to assign the issue to you.

Update the JIRA issue with your analysis of what needs to be done. This will be different for a bug, vs a new feature.

For bugs, you should explain what the bug is, and how it should be fixed.

For new features, a “one pager” or justification of the feature, (1 or 2 paragraphs) and a description of what will be done. See the section on One Pagers.

For any significant amount of work, more than half a dozen files, a One Pager, or justification for why a feature is needed, and what work will be done in order to implement it. Really, a simple design doc. It should be sufficient for Docs, and QA to get a clear understanding of the feature, and the scope. It should give references to any Specs, or other information available, and should also address things that need to be called out for testing.

The next step is to get the latest version of the project out of subversion. Even if you have checked out the source, you should always be sure you are up to date, (ie: do a svn update). For details on how to check out the latest, see the section on working with subversion.

You should also be familiar with the Coding styles used in the project.

Now that you have an issue to work on, and the latest version of the project, there are a few different paths you can take, depending on the scope of the issue, and its impact to other contributors.

For smaller issues, ones that you can complete within your own workspace, over a few days, you can just go ahead and start work!

If it is a larger issue, you might want to request a branch so that you can check in changes into your own branch without affecting anyone else. It is only when the changes are submitted to trunk, that they have to undergo the review process. If you feel you need your own branch, contact the community manager to set that up.

Once you are done with your issue, and are ready to submit it to the project, you need to create a review. Although the process will be slightly different depending on whether you have your own branch, or not, the basic flow is the same. Make sure that there is at least one core team member on the review list, as well as a member of the community team for community submissions. Please put enough information into the comments so that people who will be reviewing can quickly get the context around what was done. Anything you spent a lot of time on, or that is pretty complex, should have corresponding comments. Remember, these comments are used for several things, like input to Docs, or as knowledge base for the future. See the section on Code Reviews.

Once the review is complete, a core team member will commit your contribution into the project. You should now update the JIRA issue to resolved. (awaiting verification)

Use of Tools

There are several tools we use within the development team. Each of them is available to any community member to use, and participate in the process.
These are:

Subversion – Version Control System

JIRA – Issue Tracking System

Crucible/Fisheye – Code review System

Confluence – Wiki

Working with JIRA issues

When creating a JIRA issue, it is either a bug, or a new feature. This setting determines where the issue is going to be handled. Bugs generally go to Sustaining, and new features will go to engineering.

The Wiki has a good description on how to open JIRA issues:

https://wikis.forgerock.org/confluence/display/openam/A+guide+to+raising+OpenAM+bugs

Tasks

JIRA tasks and subtasks are used by the engineering team to track the work they need to do, and how they are progressing on it.

Tasks are generally equivalent to “user Stories” in an agile environment. This means, that a tasks is a “documentable and testable” feature. Tasks are generally closed by QA, after verification.

Sub tasks are the steps needed to get there, and I would expect that Docs and QA would put in a subtask if needed. Sub-tasks are closed by the person doing the work to indicate that subtask is complete.

Working with Subversion

There is a good guide to using subversion here:

https://wikis.forgerock.org/confluence/display/openam/Guide+to+OpenAM+Subversion

Working with One Pagers

Any development work in any of the projects needs to have a “one Pager” or a design document that can be reviewed by the Project lead, the Architecture team, and other interested stakeholders. This is not meat to be a major effort, but should be scaled roughly to the size of the contribution.

It should have the following sections:

  1. Why is this needed?
  2. Scope of effort required.
  3. High level design. Architectural decisions, support needed from other components, etc.
  4. Documentation callouts. Anything that needs to be considered by Pubs
  5. QA Callout: Anything that needs to be considered by QA.
  6. References to supporting docs. Web pages, specs, Blogs, etc.

Generally, this should not be more than one page, and could easily be stored in the comments field of the JIRA issue. If it is more significant, and needs more, it can be a PDF and stored in the JIRA issue.

Working with Crucible/Fisheye

In order to submit changes to the project source tree, one has to be at least a Fan. This means that you 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 50 lines of code, in one physical file. This is expected to be the majority of fixes for bugs raised in JIRA. Most fixes are going to be 3 or 4 lines. After review the patch is committed directly to the trunk. The 1 file/50 lines is a guideline, and is meant to give you a relative idea of the size of submission that can be done directly.

Complex Patches to trunk

Complex patches to the main trunk, are patches that affect more than 50 lines of code, and multiple 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 initially supported by ForgeRock. Any Contributor can request an extension, over which they have control. The request should include the One Pager, or design doc. 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. Please also contact community@forgerock.com with details of your extension.

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 project and subject to the normal submission process. This would include a One Pager, or design doc, just like any other significant contribution.

Submitting code changes

The way that you contribute code is consistent for all contributors. Our contribution process, for everyone, is “review then commit”.

The development process for a simple patch is:

  1. Every check-in requires a JIRA entry. If you do not have one, Create one.
  2. Check out the latest version of the trunk to a local workspace.
  3. Edit your local files making the changes you deem necessary.
  4. Build and verify your changes.
  5. 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
  6. Generate a diff using svndiff.
  7. In Crucible; create a review request and paste your diff.
  8. Add at least one Rockstar to the review. If you are contributing as a community member, you should also add the community team to the review.
  9. Update the JIRA entry to contain a full description and any details that will be useful to reviewers. Remember, this information is also very useful for times in the future where someone might be trying to understand your code.
  10. Once your patch has been reviewed a Roadie or Rockstar will commit the patch to the trunk. The commit message should reflect both the JIRA issue as well as the Code Review number. [Openam-XXXX] CR-YYY One line commit message…..

The development process for a complex patch is:

  1. Contact a Rockstar and request a branch for your submission.
  2. A branch will be created for your fixes. You will have full commit access to the branch
  3. Every check-in requires a JIRA entry. If you do not have one, Create one.
  4. Check out the latest version of the trunk to a local workspace.
  5. Edit your local files making the changes you deem necessary.
  6. Build and verify your changes.
  7. 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
  8. Create a Licenses file containing the licenses used for any licenses software.
  9. In Crucible; create a review request based on your branch and the trunk.
  10. Add at least one Rockstar to the review. If you are contributing as a community member, you should also add the community manager to the review.
  11. Update the JIRA entry to contain a full description and any details that will be useful to reviewers. Remember, this information is also very useful for times in the future where someone might be trying to understand your code.
  12. Once your contribution has been reviewed, a Roadie or Rockstar will merge it into the trunk. The commit message should reflect both the JIRA issue as well as the Code Review number. [Openam-XXXX] CR-YYY One line commit message…..

Participating in development

Anyone can participate in the development process, (as long as you are a fan). Here are the steps to follow:

  1. Find a JIRA issue that you are interested in working on, and read the notes.
  2. You can create a JIRA Entry, and add justification for the feature. If it is a major or significant new feature, you should be prepared to add a one-pager describing it, and how it will be done.
  3. Send an email to the community manager giving the issue number, and that you would like to work on it. (This avoids multiple people working on the same issue!)
  4. Check out the code from trunk, and work on a fix. Obviously you should use all resources, like the dev mailing list, if you have questions, or are asking for advice.
  5. Once you have finished, follow the process outlined above.

Working with Licenses

Licenses and copyright are very important to track in an open source project.

For modifications to existing files:

/** 
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * https://opensso.dev.java.net/public/CDDLv1.0.html or
 * opensso/legal/CDDLv1.0.txt
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at opensso/legal/CDDLv1.0.txt.
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 *
 * Portions Copyright 2012 Forgerock
 * Portions Copyright 2013 YourName
 *
 */

For New Files:

/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2013 ForgeRock AS. All Rights Reserved
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.<
 *
 * You can obtain a copy of the License at
 * http://forgerock.org/license/CDDLv1.0.html
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file<
 * at http://forgerock.org/license/CDDLv1.0.html
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * " Portions Copyrighted [year] [name of copyright owner]"
 *
 */