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.
Any questions, comments or feedback to the Community Manager, can be emailed to firstname.lastname@example.org
There are a few guiding principles for general development process.
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.
Keep people informed of things that have impact
Any API level changes should be brought to the band.
The products use many libraries, and implement many useful utility methods. Re-use them.
Tell people what you are doing, ask for help, ask for advice. Questions are good.
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:
Any contribution you make will always be under license. You can also assign the copyright if you wish.
There are many different opensource licenses all of which grant the licensee different rights. Forgerock.org prefers to use the CDDL, although many licenses are compatible, and we are able to accept. Generally, we cannot accept any code, (or dependencies on) that is licensed under GPL.
Please contact the community manager 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:
There are several ways you can contribute to the projects, and several types of 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!
You do not need to do anything to start contributing, other than to start!
If you would like to contribute more formally, to the documentation, (admin guide, or install guide, and the like,) you are more than welcome. Contact the community manager, who can help you get involved. The process will be similar to the code contribution process below.
If you would like to contribute, and are fortunate enough to speak multiple languages, you might want to get involved to help with some of the localization and translation issues. Contact the community manager who can get you set up.
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 only 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 the community manager (guruallan) 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.
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:
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 equivalentto “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.
There is a good guide to using subversion here: https://wikis.forgerock.org/confluence/display/openam/Guide+to+OpenAM+Subversion
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:
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.
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:
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 are meant for longer term projects, or sub-projects that are not initially supported by Forgerock.com. 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.
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 EVERONE, is "review then commit".
The development process for a simple patch is:
The development process for a complex patch is:
Participating in development.
Anyone can participate in the development process, (as long as you are a fan). Here are the steps to follow:
Licenses and copyright are very important to track in an opensource project.
For modifications to existing files:
For New Files: