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 based on the target branch
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.
1. Fork the main Tiki GitLab repository to your GitLab account
Select the target group you want to place your fork. It will take 15 minutes or more.
Mirroring your fork to the main Tiki repository
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
Type https://gitlab.com/tikiwiki/tiki.git in the "Git repository URL" input field
Ensure the "Mirror direction" field is set to Pull. This option is only available on GitLab Premium.
If you keep your fork clean of changes by creating separate branches as described below, then check "Overwrite diverged branches". This option is also only available on GitLab Premium.
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.
In this step, the repository you forked to your account on GitLab is cloned onto your local computer.
Examples of how to clone
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.
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:
Clone to current folder with 5 last revisions only
3. Checkout the correct target branch on your computer
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.
Checkout branch 20.x on your computer
Copy to clipboard
$ git checkout 20.x
4. Create a new branch on your computer
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.
Create a local branch
Copy to clipboard
$ 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:
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.
5. Commit changes to your local clone
The community standards for commit messages should be respected please see: Commit Message.
Commit changes to your local clone
Copy to clipboard
$ git add tiki-file.php
$ git commit -m "[FIX] Removing bad characters from registration form to avoid XSS attacks"
6. Push changes to your forked repository on GitLab
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.
If there is an issue, fix quickly or indicate in the comments that you will do later, or that you need help.
Wait and interact
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.
To backport a commit
first check that we have the branch on which we want to backport the commit if not track it
to check git branch -a to track and clone the branch's commits git remote add --track 25.x 25.x-track https://gitlab.com/keutyche/tiki.git git fetch 25.x-track --depth=500 move to a new branch with the elements we just downloaded
git checkout -b fixCorruption 25.x-track/25.x do the cherry pick git cherry-pick a12f4017cf6b13eefab06f8110ff5aa2516439d3 a12f4017cf6b13eefab06f8110ff5aa2516439d3 This is the hash of the commit after being merged
then make a push and create a new merge request to the desired branch
git push -u origin fixCorruption
Important
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.
After backporting, please make sure to reference the original MR in the description or comment. The point it to create activity on the original MR so we know it was backported, if we need to remove the tag, etc.
Manually Syncing Your Fork to the main Tiki Repository
Apply commits from the main Tiki repository to your local repository with the command git pull upstream master --rebase
Apply those commits from your local repository to your forked repository with the command git push origin master
If you get an error message after attempting this push to your forked repository and there is no other activity on that repository (e.g., it is only used by you for merge requests), try git push origin master --force
You should sync often, especially before making changes locally, and after committing but before pushing to your fork.
Fix Out-of-Sync Fork
Sometimes your forked repository can get out of sync with the main Tiki repository and your local copy. Symptoms are when you frequently have to force push to the fork, or unwanted other commits from other authors are combined into a merge request made from your fork to the main repository. Follow these steps to fix:
!! Introduction
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 based on the target branch
# __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.
!!! 1. Fork the main Tiki GitLab repository to your GitLab account
# 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.
{HTML()}
<video width="640" controls>
<source src="tiki-download_file.php?fileId=1281&display=y" type="video/mp4">
</video>
{HTML}
!!!! Mirroring your fork to the main Tiki repository
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
# Type -+https://gitlab.com/tikiwiki/tiki.git+- in the "Git repository URL" input field
# Ensure the "Mirror direction" field is set to Pull. This [https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html|option] is only available on GitLab Premium.
# If you keep your fork clean of changes by creating separate branches as described [#Create_a_new_branch_on_your_computer|below], then check "Overwrite diverged branches". This [https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html#overwrite-diverged-branches|option] is also only available on GitLab Premium.
# 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|Manually Syncing Your Fork to the main Tiki Repository].
!!! 2. Clone the forked repository to your computer
In this step, the repository you forked to your account on GitLab is cloned onto your local computer.
!!!! Examples of how to clone
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.
{CODE(colors="shell" theme="default" caption="Clone to a newly created directory named tiki")}$ git clone git@gitlab.com:fabiomontefuscolo/tiki.git tiki
{CODE}
{CODE(colors="shell" theme="default" caption ="Clone to current folder")}
$ git clone git@gitlab.com:fabiomontefuscolo/tiki.git .
{CODE}
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:
{CODE(colors="shell" theme="default" caption ="Clone to current folder with 5 last revisions only")}
$ git clone git@gitlab.com:fabiomontefuscolo/tiki.git . --depth=5
{CODE}
!!! 3. Checkout the correct target branch on your computer
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.
{CODE(colors="shell" theme="default" caption="Checkout branch 20.x on your computer")}
$ git checkout 20.x
{CODE}
!!! 4. Create a new branch on your computer
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.
{CODE(colors="shell" theme="default" caption="Create a local branch")}
$ git checkout -b fixing-left-sidebar
{CODE}
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:
{CODE(colors="shell" theme="default" caption="Create a second local branch")}
$ git checkout 20.x
$ git checkout -b fixing-xss-issue-on-register-form
{CODE}
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.
!!! 5. Commit changes to your local clone
The community standards for commit messages should be respected please see: ((Commit Message)).
{CODE(colors="shell" theme="default" caption="Commit changes to your local clone")}
$ git add tiki-file.php
$ git commit -m "[FIX] Removing bad characters from registration form to avoid XSS attacks"
{CODE}
!!! 6. Push changes to your forked repository on GitLab
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.
{CODE(colors="shell" theme="default" caption="Push changes to your GitLab fork")}
$ git push -u origin fixing-xss-issue-on-register-form
{CODE}
!!! 7. Create a new merge request from your forked repository on GitLab
The purpose of this step is to merge the changes pushed to your GitLab Tiki fork to a specific branch in the [https://gitlab.com/tikiwiki/tiki?nav_source=navbar|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
{HTML()}
<video width="640" controls>
<source src="tiki-download_file.php?fileId=1282&display=y" type="video/mp4">
</video>
{HTML}
!!!! Check your merge request via the web interface
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.
!!!! Wait and interact
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.
!!!! To backport a commit
first check that we have the branch on which we want to backport the commit if not track it
__to check__
-+ git branch -a+-
__to track and clone the branch's commits__
-+git remote add --track 25.x 25.x-track https://gitlab.com/keutyche/tiki.git+-
-+git fetch 25.x-track --depth=500+-
move to a new branch with the elements we just downloaded
-+git checkout -b fixCorruption 25.x-track/25.x+-
__do the cherry pick__
-+git cherry-pick a12f4017cf6b13eefab06f8110ff5aa2516439d3+-
a12f4017cf6b13eefab06f8110ff5aa2516439d3 This is the hash of the commit after being merged
then make a push and create a new merge request to the desired branch
-+git push -u origin fixCorruption+-
!!!! Important
* When commands like -+git reset ~np~--hard~/np~+- or -+git push ~np~--force~/np~+- is needed, it may be that there is a problem with the workflow and it should be planned again.
* After backporting, please make sure to reference the original MR in the description or comment. The point it to create activity on the original MR so we know it was backported, if we need to remove the tag, etc.
!!!! Manually Syncing Your Fork to the main Tiki Repository
An alternative to mirroring your fork as described in [#Mirroring_your_fork_to_the_main_Tiki_repository|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 {CODE()}git remote add upstream https://gitlab.com/tikiwiki/tiki.git{CODE}
+ 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 --rebase+-
# Apply those commits from your local repository to your forked repository with the command -+git push origin master+-
## If you get an error message after attempting this push to your forked repository and there is no other activity on that repository (''e.g.'', it is only used by you for merge requests), try -+git push origin master --force+-
You should sync often, especially before making changes locally, and after committing but before pushing to your fork.
!!!!! Fix Out-of-Sync Fork
Sometimes your forked repository can get out of sync with the main Tiki repository and your local copy. Symptoms are when you frequently have to force push to the fork, or unwanted other commits from other authors are combined into a merge request made from your fork to the main repository. Follow these steps to fix:
{CODE(colors=shell)}
git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --force
{CODE}
!! See also
* ((Backport changes using Git))
* ((Tiki Unit Testing))
-=alias=-
* (alias(Git workflow For Collaborators))
~tc~ (alias(How to get commit access)) ~/tc~
The following is a list of keywords that should serve as hubs for navigation within the Tiki development and should correspond to documentation keywords.
Each feature in Tiki has a wiki page which regroups all the bugs, requests for enhancements, etc. It is somewhat a form of wiki-based project management. You can also express your interest in a feature by adding it to your profile. You can also try out the Dynamic filter.