Contribution Workflow - For teams
This page outlines a workflow for teams wishing to collaborate on a community project. Individuals performing small changes, bug-fixes an so on should follow the ForgeRock Development Process . An over view of the process can be seen in the figure below, using a OpenIDM as an example central repository.
The following sections will show this workflow in action. In the examples we will follow a fictitious company called Acme that has a distributed team of engineers that will work on a new feature to contribute to a central project called 'OpenFLOW'.
You will need a ForgeRock user account to work with some of the tools. You can create your free account at https://backstage.forgerock.com.
1 Create a Jira issue for the work you want to do.
Depending on the size of the work you may want to create an epic with multiple stories. Stories may have tasks associated with them that can be assigned to different people, so a story should represent a cohesive testable piece of functionality. An Epic may comprise of a number of stories. Choose COMMUNITY as a tag for your Epic or Story so it may be found by our community team.
2 Fork the Central Repository to the Community project.
Currently you will have to contact the ForgeRock community team to have them create a fork for you due to the permissions on the We will be working on automating this step during 2016. We will assume that ForgeRock have created a fork of the OpenFLOW project in the Community project and named it 'OpenFLOW-Acme' to indicate that the repository being used by the 'Acme' group;
3 Create a branch for the feature you're developing.
This branch will act as the feature branch, with contributors merging their changes into that branch. Naming should indicate the Jira Story that is being implemented, e.g. OpenFLOW-1640-write-intro-readme-section.
The following sections must be followed by each individual working on the feature
4 Fork the Community Fork
Individual Contributors to the Feature must Fork the repository to their own area of Stash.
Now we will create a branch for our (individual) work on this feature and clone the repository to our local machine.
5 Create a branch for our Individual Work on this Feature
This will often be tied to a story in Jira, in which case, you can use Jira to create the branch for you using the create branch option on the right hand pane of the JIRA page. This will ensure the branch gets a suitable name that enables Jira to create a link between the branch, pull request and issue.
Or create it directly from within Bitbucket server, Starting the branch name with the JIRA issue id.
Be sure to branch from the feature branch, not from Master! You will be merging your work back into the feature branch, so this is where you will branch from.
6 Clone your Fork to your Dev Machine
From your private repository page you can find the http url of the git repository;
Copy the http url and then clone your fork to your local machine from the command line - your repository's url will be substituted for
repo-url in the command below;
git clone <repo-url>
git checkout feature/OpenFLOW-1640-write-intro-readme-section-jpublic
If you would rather use SSH you can follow this guide to set up SSH keys for your account. This can save a lot of typing of usernames and passwords
7 Make Your Changes
Please bear in mind the points about coding style, commit message and so on as described in step 5 Making Your Changes of the ForgeRock Development Process.
Because only you are working on your branch, it is OK to perform interactive rebases, rewrite history and force pushes to your fork. Keeping your history simple an concise makes understanding the history less taxing.