Git¶
phpBB uses Git for its version control system. The phpBB Git repository is hosted on GitHub at https://github.com/phpbb/phpbb.
This documentation explains how to contribute to phpBB development:
Basics¶
phpBB Repository¶
Forking and Cloning¶
To contribute to phpBB development, you should sign up for a GitHub user account if you don’t already have one.
Begin by forking the phpBB repository to your account, by clicking the “Fork” button at phpBB’s repository.
Clone your fork of phpBB’s repository to your computer:
git clone git://github.com/<my_github_name>/phpbb.git
See Set Up Git for help on setting up Git.
Branches¶
master - The latest unstable development version with new features etc.
3.3.x - Development branch of the 3.3 line. Bug fixes and minor feature changes are applied here.
3.2.x - Development branch of the 3.2 line. Bug fixes and minor feature changes are applied here.
3.1.x - Development branch of the stable 3.1 line. phpBB 3.1 has reached its End of Life and is therefore no longer maintained.
3.0.x - Development branch of the stable 3.0 line. phpBB 3.0 has reached its End of Life and is therefore no longer maintained.
2.0.x - Development branch of the deprecated 2.0 line.
Tags¶
Tags are released versions. Stable ones get merged into the master branch.
release-3.Y.Z-aX - Alpha release X of the 3.Y.Z line.
release-3.Y.Z-bX - Beta release X of the 3.Y.Z line.
release-3.Y.Z-RCX - Release candidate X of the stable 3.Y.Z release.
release-3.Y.Z - Stable 3.Y.Z release.
release-2.0.X - Deprecated stable 2.0.X release.
This means all bug-fix development should take place on the 3.2.x branch, and will be merged into higher branches, including master. All feature development should take place in master. Read more about the workflow in the next section.
How to contribute?¶
When fixing a bug, please post in the bug tracker.
When adding a feature to 3.x post your patch for review in a new topic on the
[3.x] Discussion forum at
Area51. Please either provide a link to your commit or branch on GitHub or
attach a patch created with git format-patch
. For larger features or changes
consider adding it as an idea to phpBB Ideas or posting an RFC on Area51 first.
Branch Names¶
Feature branches should be called feature/feature-name. Bug or minor improvements do not need a name, their branches should be called ticket/1234 with the correct ticket id. If you want to give something a name that is not a feature you may use task/task-name. When these branches go into the main phpBB repository they are renamed <category>/<user>/<name-or-id> or user/<category>/<name-or-id> to make clear from which developer’s repository the branch was merged.
Commit Messages¶
You should always create a ticket before starting work. It is important that every commit references a ticket. It does not matter what state that ticket is in. No line should contain more than 79 characters. The first line should be followed by a blank line. This means you should not break the first sentence of your message! The purpose of this is to maintain useful –oneline logs which only display the first line of every message. A good commit message then looks like this:
[branch you are working on] A short explanation of the change.
A more detailed explanation of which things exactly were changed and for
what reasons.
This can span multiple paragraphs for a bigger change. And
it should really make clear all the changes to anyone reading this commit
message without further context.
TICKET-ID
An example:
[feature/request-class] Adding request class ported from ascraeus-experiment.
The well known request_var function is now a wrapper that calls a method
on a phpbb_request object. The class provides additional functionality.
It can replace all super globals with special objects that throw errors
when being accessed. They still allow isset operations to keep backward
compatibility with isset($_POST['var']) checks. The phpbb_request class
implements the phpbb_request_interface which is available for easy mocking
of input in tests.
PHPBB-1234
The structure of a commit message which is verified by the commit-msg hook is as follows:
[<branch>] <summary>
<description>
<ticket1>
<ticketn>
The required components are the summary, branch, and list of tickets; the description is optional. Both the description and ticket list must be preceded by a single empty line. The description element is unrestricted length and may contain any number of empty lines to separate paragraphs; each ticket in the list must be on its own line. If the branch is a [ticket/] branch, the ticket list must contain a matching ticket, finally the ticket list may not contain any duplicates.
Developers¶
Review Forking and Cloning.
Configuration¶
Git¶
Add your Username to Git on your system:
git config --global user.name "Your Name Here"
Add your E-mail address to Git on your system:
git config --add user.email username@phpbb.com
Add the upstream remote (you can change ‘upstream’ to whatever you like):
git remote add upstream git://github.com/phpbb/phpbb.git
Note
The upstream remote url is the phpBB GitHub repo. Your cloned fork of the phpBB GitHub repo will, by default, use the origin remote url.
Composer¶
To be able to run an installation from the repo (and not from a pre-built package) you need to run the following shell commands to install phpBB’s dependencies.
cd phpBB
php ../composer.phar install
Ignore any abandoned package warnings.
See also
Introduction - Composer for further information.
Hooks¶
The phpBB repository contains some client-side hooks that can aid development. They are
located in the git-tools/hooks
directory. These hooks do things like preparing and
validating commit messages, checking for PHP syntax errors. There is a script to set
them up (which symlinks them into .git/hooks
).
cd git-tools/hooks
./install
In case you get an error, stating the hooks already exist. Simply remove all files from .git/hooks
and re-run the install command.
Once these hooks are installed, you simply need to run git commit
to commit new
changes. Depending on your environment, you will be prompted to add a commit message
using Vim or
Emacs. The
hooks will take care of formatting your entire commit message in the required format
(see Commit Messages).
Creating local branches¶
To work on phpBB you need to create local branches of whichever develop branch (e.g. master) you need. Issue the following command to perform this operation:
git checkout -b master origin/master
Workflow¶
Pulling in upstream changes¶
You will need to merge in changes made to the upstream repository for them to appear in
your fork, the steps to do this follow. We’re assuming you are performing this on the master
branch, but it could be a bug fix branch or a develop release branch, so ensure you are on
the correct branch using git branch
and change with git checkout
if required.
1. Pull the changes from the upstream master branch:
git pull upstream master2. Push the changes back to your fork (substitute master for the current branch):
git push origin master
The following image visualises the phpBB branching model. It may help you to understand the different branches this section refers to later.
Bug fixing¶
Ensure you are using the correct develop branch (e.g. 3.2.x) first and not the master branch. In this example we are using 3.2.x.
git checkout 3.2.x # Checkout the base branch 3.2.x
git branch ticket/12345 # Create a new branch for your bug fix
git checkout ticket/12345 # Switch to the new branch
# Make your changes
git add <files> # Stage the files
git commit # Commit staged files - please use a correct commit message
# Make more changes & commits if necessary
git push origin ticket/12345 # Push the branch back to GitHub
Starting a new feature¶
Ensure you are using the correct develop branch (e.g. master) first. In this example we are using master.
git checkout master # Checkout the base branch
git checkout -b feature/my-fancy-new-feature # Create a new branch for your feature & switch to it
# Make your changes
git add <files> # Stage the files
git commit # Commit staged files - please use a correct commit message
# Make more changes & commits
git push origin feature/my-fancy-new-feature # Push the branch back to GitHub
Collaborating with other developers on a feature¶
You have pushed a new feature to GitHub and another developer has worked on it. This is how you can integrate their changes into your own feature branch.
git remote add otherdeveloper git://github.com/otherdeveloper/phpbb.git # Add the other developer's repository as a remote
git fetch otherdeveloper # Fetch otherdeveloper's changes
git checkout feature/my-fancy-new-feature # Switch to the feature branch
git merge otherdeveloper/feature/my-fancy-new-feature # Merge otherdeveloper's changes into your feature branch
# If necessary resolve conflicts & commit
git push origin feature/my-fancy-new-feature # Push the branch back to GitHub
Merging a feature or bugfix branch¶
Once a feature or bug-fix is complete it can be merged back into the master branch. To preserve history we never fast-forward such merges. In this example we will merge the bug-fix created earlier into 3.2.x. We then merge the changes into 3.3.x and then merge 3.3.x into master to keep these branches up to date.
git checkout 3.2.x # Branch we want to merge into, pull in upstream changes first.
git merge --no-ff remote/ticket/12345 # Merge remote branch without fast forward
git checkout 3.3.x # Branch we want to merge into, pull in upstream changes first.
git merge --no-ff 3.2.x # Merge to keep the 3.3.x branch in sync
git checkout master # Branch we want to merge into, pull in upstream changes first.
git merge --no-ff 3.3.x # Merge to keep the master branch in sync
git push origin 3.2.x 3.3.x master # Push the three changed branches back to GitHub
Additionally the merge.log config setting of Git is set to true, producing a summary of merged commits.
Merging into phpBB repository¶
This only applies to Development Team Members. The following steps should be taken when merging a topic branch into the phpBB repository.
Note
Note that tests should be run prior to merging to the official repository. Tests are run for each push to a pull request by Github Actions but it is a good idea to run them yourself as well. For more information, read Testing.
Merging only to master¶
Note
The upstream remote below is pointing to the official phpBB repository, and origin points to your fork.
git remote update upstream
git checkout master
git reset --hard upstream/master
git merge --no-ff <author>/<branch> # example: git merge --no-ff naderman/ticket/000000
git push origin master
# Before continuing, look at your commit list in your fork to make sure it looks correct.
# If unsure, ask.
git push upstream master
Merging to 3.3.x¶
Warning
ALL merges to 3.3.x must also be merged to master!
git remote update upstream
git checkout 3.3.x
git reset --hard upstream/3.3.x
git merge --no-ff <author>/<branch> # example: git merge --no-ff naderman/ticket/000000
git push origin 3.3.x
git checkout master
git reset --hard upstream/master
git merge --no-ff 3.3.x
git push origin master
# Before continuing, look at your commit list in your fork to make sure it looks correct.
# If unsure, ask.
git push upstream 3.3.x
git push upstream master
Merging to 3.2.x¶
Warning
ALL merges to 3.2.x must also be merged to 3.3.x and master!
git remote update upstream
git checkout 3.2.x
git reset --hard upstream/3.2.x
git merge --no-ff <author>/<branch> # example: git merge --no-ff naderman/ticket/000000
git push origin 3.2.x
git checkout 3.3.x
git reset --hard upstream/3.3.x
git merge --no-ff 3.2.x
git push origin 3.3.x
git checkout master
git reset --hard upstream/master
git merge --no-ff 3.3.x
git push origin master
# Before continuing, look at your commit list in your fork to make sure it looks correct.
# If unsure, ask.
git push upstream 3.2.x
git push upstream 3.3.x
git push upstream master
Merging to 3.3.x and master with different patches¶
Warning
ALL merges to 3.3.x must also be merged to master!
Patch author creates fix-3.3
Patch author merges his fix-3.3 into a fix-master branch
Patch author changes fix-master until it works as expected
Patch author sends 2 Pull Requests
Merger merges Authors fix-3.3 into his 3.3.x
Merger merges Authors fix-master into his master
Merger merges his 3.3.x into master (should work fast-forward)
Merger verifies the results
Merger pushes 3.3.x and master to phpbb
Merging to 3.2.x, 3.3.x and master with different patches¶
Warning
ALL merges to 3.2.x must also be merged to 3.3.x and master!
Patch author creates fix-3.2
Patch author merges his fix-3.2 into a fix-3.3 branch
Patch author changes fix-3.3 until it works as expected
Patch author merges his fix-3.3 into a fix-master branch
Patch author changes fix-master until it works as expected
Patch author sends 3 Pull Requests
Merger merges Authors fix-3.2 into his 3.2.x
Merger merges Authors fix-3.3 into his 3.3.x
Merger merges Authors fix-master into his master
Merger merges his 3.2.x into 3.3.x (should work fast-forward)
Merger merges his 3.3.x into master (should work fast-forward)
Merger verifies the results
Merger pushes 3.2.x, 3.3.x and master to phpbb
Fixing merge conflicts¶
Merge conflicts must always be solved by using the git rebase functionality. Do not merge the base branch, e.g. master, in order to solve potential merge conflicts or in order to update your branch.
To update your branch, you can often run a simple rebase:
Checkout your feature or bugfix branch
Make sure there are no unstaged changes and that your branch has already been pushed to your remote (this can later allow you to undo your rebase changes)
Run git rebase
Force push your branch to your remote
The commands for this are as follows:
git checkout ticket/12345
git fetch upstream # ensure upstream is up to date
git rebase upstream/3.3.x # rebase on top of upstream's 3.3.x branch
git push origin ticket/12345 -f
In case you think something went wrong or there are too many merge conflicts, you can abort the rebase by running:
git rebase --abort
More difficult rebases and when switching the base branch, it makes sense to use the three-way –onto for rebasing:
git rebase --onto new_base_branch old_base_branch ticket/12345
Where
new_base_branch is the new base branch your bugfix branch should be based on
old_base_branch is the old base branch your bugfix branch is based on before the rebase
ticket/12345 is the name of your bugfix or feature branch
Windows¶
If you use git on Windows you should disable the AutoCrlf
which automatically
translates \n
to \r\n
.
If you don’t use TortoiseGit: To do that you must use the following command:
git config core.autocrlf input
If you want to apply to all repositories you may use the --global
option. Like this:
git config --global core.autocrlf input
The difference is that, if you don’t use the global option, any new repository you create will not have this option properly set for phpBB development which may cause errors to occur while committing or when executing any php file.
For those who use TortoiseGit (and used to work with TortoiseSVN):
When you use TortoiseGit the first time, you need to disable AutoCrlf
in
Settings > Git > Config, so your line-ends are not changed from LF to CR-LF.
You also need to edit the local .git/config
and add the following code, so you
can correctly merge branches (you need to do that on every git repository you have):
[merge]
log = True
Create your own SSH key¶
TortoiseGit will automatically use the SSH key
Note
I used the OpenSSH option during installation, so I am not sure if this works for the other option or if you are supposed to do it some other way.
Clone¶
Then simply clone the repository to your local system and the rest is mostly like TortoiseSVN.
Commands¶
Pull |
Grab the updates from upstream |
Commit |
Commit the changes locally (you must Push or Sync to commit the changes to the repository) |
Push |
Push the changes that were made locally to the online repository |
Sync |
Pushes/Pulls changes with more options |
Tip
Always Pull first, then Commit, then Push; this will help you to not end up with merge conflicts.
Further reading¶
External links¶
TortoiseGit - A windows Git client based on TortoiseSVN
TortoiseGit on github - GitHub repository