4.2.1 Fork your own country configuration repository
Previous4.2 Set-up your own, local, country configurationNext4.2.2 Set up administrative address divisions
Last updated
Last updated
The first step towards configuring your own country configuration of OpenCRVS is to fork our existing country configuration based on our demonstration country Farajaland - Repo: opencrvs-countryconfig. the following steps help you change the cloned Farajaland repo into your own country configuration fork.
When you ran the bash setup.sh script 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-countryconfig directory to something like "opencrvs-<your country>".
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.
Create a new, private Git repository named the same as your new directory, ie: "opencrvs-<your country>" on your organisation's account on Github.
Copy the Git URL to this repository, e.g. https://github.com/<your organisation>/opencrvs-<your country>.git
In Terminal, cd inside your local directory for the country configuration, opencrvs-<your country>. If you run git remote -v inside 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:
You can check that the origin URLs have changed successfully by running git remote -v again.
Ensure that you are on the master branch of the country configuration folder: git checkout master
Run git push to push the example Farajaland code to your repo. Once the files are pushed you should see the country configuration code on your own Github repo.
We strongly recommend that you set up a Gitflow branching strategy on your repo to ensure that you can develop features on feature branches, merge them into develop for testing and main or master for releases. Therefore create a companion develop branch that you will use for developing the rest of your configuration: git checkout -b develop & then push that code up to your new repository with git push
It is very important that you configure branch protection rules on your master, develop and main branches as these branches should not be able to be pushed to by any developer without a pull request for code review.
In the above example, a "classic" branch protection rule is being created on the branch "main". The following settings should be checked:
Require a pull request before merging / Require approvals
Require review from Code Owners Require status checks to pass before merging / Require branches to be up to date before merging
Restrict who can push to matching branches
The following should be unchecked:
Allow force pushes
Allow deletions
Following best practices, we recommend that you setup branch protection rules so that no developer can push code to your important branches without a pull request
It's up to your team to decide how you wish to manage pulling future release code from our countryconfig / "farajaland" repo. An example strategy is explained below.
Add in our countryconfig repo as a new remote and call it 'upstream'
Maintain a new branch that you use to pull in latest releases. You can use this to review changes in a pull request before fixing conflicts.
