3.2.1 Fork your own country configuration repository
The first step towards configuring your own country configuration of OpenCRVS is to fork our existing country configuration based on our demonstration country Farajaland. the following steps help you change the cloned Farajaland repo into your own country configuration fork.
- 1.When you ran the
bash setup.shscript in step 3.1.2 to install OpenCRVS locally, the country configuration repo for Farajaland was cloned into the same parent directory as opencrvs-core, as you are probably aware. The first thing that you want to do is to change the name of the cloned opencrvs-farajaland directory to something like "opencrvs-<your country>". - 2.Next, we strongly recommend that you create or use an existing organisation account on Github for storing your country configuration fork so that you can share access amongst your internal team safely.
- 3.Create a new, private Git repository named the same as your new directory, ie: "opencrvs-<your country>" on your organisation's account on Github.
- 4.Copy the Git URL to this repository, e.g. https://github.com/<your organisation>/opencrvs-<your country>.git
- 5.In Terminal,
cdinside your local directory for the country configuration, opencrvs-<your country>. If you rungit remote -vinside this directory you should see that the origin Git URLs are still pointing to our Farajaland repo. We need to point these origin URLs to your repo. To do that, run this command:git remote set-url origin https://github.com/<your organisation>/opencrvs-<your country>.git - 6.You can check that the origin URLs have changed successfully by running
git remote -vagain. - 7.Ensure that you are on the master branch of the country configuration folder:
git checkout master - 8.Run
git pushto push the Farajaland code to your repo. Once the files are pushed you should see the country configuration code on your own Github repo. - 9.We strongly recommend that you set up a Gitflow branching strategy on your repo to ensure that you can develop features on custom branches. Such as: master-<your country alpha3 code>, develop-<your country alpha3 code>, release-<your country alpha3 code>-v<release-number> branches without impacting our Farajaland master, develop (which has already moved on from the latest release) or release-v<release-number> branches.
- 10.As the master branch is aligned to the latest release, from the master branch you can create these branches by running:
- 11.
git checkout -b master-<your country alpha3 code> - 12.
git push --set-upstream origin master-<your country alpha3 code> - 13.
git checkout -b develop-<your country alpha3 code> - 14.
git push --set-upstream origin develop-<your country alpha3 code> - 15.You do not need release branches now, but hopefully the concept is clear of what to do when that time arises for you.
- 16.Additionally we recommend that you setup branch protection rules so that no developer can submit code to your new master, develop or release branches by mistake without a code review. In Github settings you can set your develop-<your country alpha3 code> branch as your default branch to make things easier for your developers.
- 17.Now you can add the Farajaland repo back in as a remote repo (not an origin) so that when you later run
git fetch --allyou can get all our branch changes and yours:git remote add farajaland [email protected]:opencrvs/opencrvs-farajaland.git
Note: The reason we recommend this branching strategy is because, when we release new versions of OpenCRVS Core & our default Farajaland country configuration, you will need to temporarily set the origin URLs back to https://github.com/opencrvs/opencrvs-farajaland.git and pull changes from the Farajaland master, develop & release- branches and then rebase in any conflicts to your custom branches. In this way you can stay up to date and use this repo as a true fork.