In OpenLP we'll be using the following workflow. This allows us to work efficiently, keep our code at it's best, work independently and keep features isolated.
If you haven't yet read the page on Git, it is recommended that you do that before reading this page.
Utilities that help
For those who like GUI's, there are a number of GUIs for Git that you can download and install for Linux, Windows and Mac OS X.
When we first developed OpenLP we decided not to write tests "to get the first release out faster." This was a bad idea and we're paying for it now. The codebase has numerous bugs and structural issues which decent tests from the beginning could have prevented. In order to help prevent further problems, we now try to practice an informal form of Test-Driven Development.
Thanks to our absence of tests historically, we have a huge amount of technical debt in unwritten tests. In order to lessen this technical debt, every single merge is required to contain at least one new test. Ideally, if you are adding a feature, your feature should be thoroughly tested. The only way to know something works properly is to write tests for it.
Take a look at our page on writing tests for more in-depth information.
At the time of writing we have 54% of our codebase covered by tests. This number should obviously be 100% but it's not going to be an overnight transformation. Use the
coverage plugin for
nose to see which lines are covered, and which are not.
One of the great things about viewing the code coverage is that it gamifies writing tests.
Version Control Workflow
The core of the development workflow is the version control workflow.
Here's a diagram to help you understand how the workflow works:
The first thing you'll want to do is to "fork" the repository on GitLab. Forking means to create a personal clone of the main repository under your user on GitLab.
Once you've created a fork, you'll want to clone your personal fork:
git clone firstname.lastname@example.org:<username>/openlp.git
This will create a directory on your computer called
openlp. The next step is to link your local repository to the main repository, and call that link
git remote add upstream https://gitlab.com/openlp/openlp.git
Please note: You cannot commit or push to
upstream (aka the main repository). The main repository is read-only for anyone other than the OpenLP core team.
See more information on the Using Git page.
When you want to do some work in a particular area, or on a particular area, you'll want to create a new branch for this work. Once this branch is created, you'll work in it until you've completed what you set out to do.
First make sure your master is up-to-date:
git co master git pull upstream master
Now let's create a new branch:
git branch dual-display
Great! Once this command is finished, I'll have a branch called
dual-display. Now I can work in this branch until I've got all the dual display code looking and working nicely. Note that this branch only exists in my local repository at this point.
When I've made some changes, and they work, and I'm happy with them, I can commit my changes to this branch so that I create a new revision, and I don't lose the changes. Committing changes only updates my local repository, it does not share the changes with anyone else.
git add <files that you changed> git commit -m "Add a button to identify the screens"
If you get tired of adding and then committing for each set of changes, you can add the
-a argument when committing, which will commit all modified files. Please note: any new files will not be added automatically, you will need to add them manually yourself.
git commit -am "Add a button to identify the screens"
If you've fixed a bug or implemented a feature that is referenced in an issue in GitLab, and you tag it in your commit message prefixed by "fixed" or "closes", GitLab will automatically close the issue for you.
git commit -am "Fix crash on start up, closes #123"
Run Tests Locally
If all the tests pass, including your own, you can push the code up to GitLab.
When your code is at a stage where you want to merge it with the main repository, you first need to push it up to your personal repository on GitLab:
git push origin dual-display Enumerating objects: 48, done. Counting objects: 100% (48/48), done. Delta compression using up to 8 threads Compressing objects: 100% (30/30), done. Writing objects: 100% (30/30), 6.50 KiB | 739.00 KiB/s, done. Total 30 (delta 25), reused 0 (delta 0) remote: remote: To create a merge request for upgrade-web-remote, visit: remote: https://gitlab.com/<your username>/openlp/-/merge_requests/new?merge_request%5Bsource_branch%5D=dual-display remote: To gitlab.com:<your username>/openlp.git * [new branch] dual-display -> dual-display
Requesting a Merge
As you can see GitLab very kindly includes a link in the output from the push command for you to create a merge request. Just copy and paste this link into your browser, and you'll be able to request a merge from there.
Running Your Tests on GitLab
Every time you push your code up to GitLab, GitLab will automatically run all the tests in its CI pipeline. Any merge requests that have failing tests will not be approved by the core developers.
Once the merge has happened, most folk will want to update their local master.
git co master git pull upstream master
Don't forget to update your remote master too:
git push origin master