This article explains the workflow that should be followed to contribute to the Tiki GitLab repository at https://gitlab.com/tikiwiki/tiki. Following are the main steps:
- Fork the main Tiki GitLab repository to your GitLab account
- Clone the forked repository to your computer
- Checkout the correct target branch on your computer
- Create a new branch on your computer
- Commit changes to your local clone
- Push changes to your forked repository on GitLab
- Create a new merge request from your forked repository on GitLab
Each of these steps is explained in more detail below.
- Create an account at https://gitlab.com
- Go to Tiki project page, https://gitlab.com/tikiwiki/tiki
- Click on fork badge at top right corner
- Select the target group you want to place your fork. It will take 15 minutes or more.
At this point, you will probably want to mirror your forked repository to the main Tiki repository so that your fork will be automatically updated for any commits to the main repository. To do this:
- Go to the project page of your forked repository
- In the menu on the left, click on Settings > Repository
- Find the "Mirroring repositories" subheading and click the Expand button
https://gitlab.com/tikiwiki/tiki.gitin the "Git repository URL" input field
- Ensure the "Mirror direction" field is set to Pull
- Click on the "Mirror repository" button
Your forked repository will be synced at least every hour. The main Tiki branches in your fork should not diverge from the main Tiki repository, otherwise the mirroring will fail or the branch on your fork will be overwritten (if you selected that option). This is another reason to keep the main branches clean and create a temporary local branch whenever making changes as discussed in number 4 below.
If mirroring stops working (which sometimes happens), you can manually sync each time before you start coding by following the steps below at Manually Syncing Your Fork to the main Tiki Repository.
In this step, the repository you forked to your account on GitLab is cloned onto your local computer.
The examples below use Git command line, but it can be performed in any Git client embedded in an IDE. Also fabiomontefuscolo is the GitLab user in this example and it should be replaced by GitLab user who forked the repository. Only one of the following examples (or another variation not shown here) should be applied.
$ git clone firstname.lastname@example.org:fabiomontefuscolo/tiki.git tiki
$ git clone email@example.com:fabiomontefuscolo/tiki.git .
As Git will checkout all revisions since the beginning of Tiki (over 70 000 commits), will take quite a while, so you may want to limit this as in the following example:
$ git clone firstname.lastname@example.org:fabiomontefuscolo/tiki.git . --depth=5
For each major version of Tiki, there is a working branch. If the contribution is a fix for version 20.1 for example, the contributor must checkout the branch 20.x.
Note that unlike with SVN, checking out a branch with git does not mean downloading all of the tiki files for the branch into a separate folder. The folder where you cloned your fork will still be used, and the files in the folder will changed to reflect the branch that you've checked out.
$ git checkout 20.x
This is a very important step. It is a good idea to create another branch for the contribution. According to earlier steps, the repository now is set to branch 20.x and a new branch will start from this point. Suppose branch with the name fixing-left-sidebar, the following command will create this branch.
$ git checkout -b fixing-left-sidebar
If for some reason the contributor needs to stop his work and start a new one for the same branch 20.x, he can simply commit or stash his changes, switch back to 20.x and create the new contribution he needs. For example, a new urgent task appeared to fix a security issue:
$ git checkout 20.x $ git checkout -b fixing-xss-issue-on-register-form
In this way, the contributor can have two ore more unrelated jobs (fixing-left-sidebar and fixing-xss-issue-on-register-form) for the same target branch (20.x). It will also help on Merge Request creation. Please see the Atomic commit convention
Similar to checking out a branch, a new local branch that you've created will still reside in the same folder that you cloned your forked repository into. As explained above, creating local branches is a simple and quick way to isolate different sets of changes so that you are always able to quickly switch back to a clean copy or between sets of changes.
The community standards for commit messages should be respected. Remember to give a meaningful commit message and prefix it with a suitable tag explained in Commit Tags.
$ git add tiki-file.php $ git commit -m "[FIX] Removing bad characters from registration form to avoid XSS attacks"
In order to have changes available to create a new Merge Request, it is necessary to push the created branch to your forked repository on GitLab.
$ git push -u origin fixing-xss-issue-on-register-form
The purpose of this step is to merge the changes pushed to your GitLab Tiki fork to a specific branch in the main Tiki GitLab repository.
- Go to your forked repository page in GitLab https://gitlab.com/fabiomontefuscolo/tiki
- Then put mouse over Repository and click on Branches entry
- Locate the branch desired (eg.: fixing-xss-issue-on-register-form) and then click on Merge Request button
- On top right corner, click on Change branches and select the correct target branch (eg.: 20.x)
- Write a detailed description. Include steps to reproduce a bug if needed or how to test a new feature
Here is an example: https://gitlab.com/tikiwiki/tiki/merge_requests/18/diffs
Find yours here: https://gitlab.com/tikiwiki/tiki/merge_requests/
Make sure you are respecting the Atomic commit convention
If there is an issue, fix quickly or indicate in the comments that you will do later, or that you need help.
Maintainers may ask you changes on that pull request. In this case, just checkout the branch related to the merge request, add new commits and push it again.
When commands like
git reset --hard or
git push --force is needed, it may be that there is a problem with the workflow and it should be planned again.
An alternative to mirroring your fork as described in Mirroring your fork to the main Tiki repository, is to manually sync it as follows:
- Add the main Tiki repository as a remote with the command
git remote add upstream https://gitlab.com/tikiwiki/tiki.git
Note, you only need to do this step once
- Apply commits from the main Tiki repository to your local repository with the command
git pull upstream master
- Apply those commits from you local repositofy to your forked repository with the command
git push origin master