Git

From phpBB Development Wiki

This gives some documentation on using git for phpBB development, details of the phpBB git infrastructure documents the repositories and branches available for use.

Basics

phpBB3

Cloning

Clone the main phpBB3 repository.

git clone git://github.com/phpbb/phpbb3.git

Branches

develop - The latest unstable development version with new features etc. View on GitHub
develop-* - Development branches of stable phpBB releases. Branched off of develop.
- develop-olympus - Development branch of the stable 3.0 line. Bug fixes are applied here. View on GitHub
- develop-ascraeus - Development branch of the stable 3.1 line. Bug fixes are applied here.
master - Release. View on GitHub
qa - A branch containing all phpBB3 release candidates and stable releases. View on GitHub

How to contribute?

When fixing a bug, please post in the bug tracker. When adding a feature to 3.1 post your patch for review in a new topic on the 3.1/Ascraeus RFCs & Patches 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 posting an RFC on area51 first.

phpBB4

Repository

git://github.com/phpbb/phpbb.git

Branches

develop - Latest unstable development with new unreleased features View on GitHub
master - Release View on GitHub

How to contribute?

Please post your changes for review in a new topic on the 4.0/Rhea RFCs & Patches 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 changes consider writing an RFC first.

phpBB2

Repository

git://github.com/phpbb/phpbb3.git

Branches

master-phpbb2 - Release View on GitHub

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.

PHPBB3-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

Developers should fork a copy of the repository on GitHub from [1] and then clone as instructed by GitHub. That should involve a command such as

git clone git@github.com:<my_github_name>/phpbb3.git

so in preparation you'll need your own github account, then browse to the phpbb github repo, click the 'fork' button

Configuration

E-mail address:

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/phpbb3.git
```

NB the upstream remote url is the phpbb github repo, while you are cloning from your fork of the phpbb github repo

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 script.

Creating local branches

To work on phpBB you need to create local branches of whichever develop branches you need, issue the following command to perform this operation:

git checkout -b develop origin/develop

Workflows

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. I'm assuming you are performing this on the develop 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.

Pull the changes from the upstream develop branch:
```
git pull upstream develop
```
Push the changes back to your fork (substitute develop for the current branch):
```
git push origin develop
```

The following image visualises the phpBB 3 branching model. It may help to understand the different branches this section refers to later.

View in large or as svg.

Bug fixing

Ensure you are using the correct develop branch first and not a master branch. In this example we are using develop-olympus.

git checkout develop-olympus # Checkout the base branch
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: Git Commit Messages
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 first and not a master branch. In this example we are using develop.

git checkout develop # 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: Git Commit Messages
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/phpbb3.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 bugfix is complete it can be merged back into the develop branch. To preserve history we never fast forward such merges. In this example we will merge the bugfix created earlier into develop-olympus. We then merge the changes into develop to keep that branch up to date.

git checkout develop-olympus # 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 develop # Branch we want to merge into, pull in upstream changes first.
git merge --no-ff develop-olympus # Merge to keep the develop branches in sync
git push origin develop-olympus develop # Push the two changed branches back to github

Additionally the merge.log config setting of Git is set to true, producing a summary of merged commits.

Windows

If you use git on windows you should disable the AutoCrlf which translates "\n" to "\r\n" automatically.

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)

NOTE: 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

http://help.github.com/win-set-up-git/

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: Commits the changes locally (you must Push or Sync to commit the changes to the repository)

Push: Pushes the changes that were locally made into the 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.

External links

Official Git homepage
GitHub
phpBB GitHub account
TortoiseGit - A windows Git client based on TortoiseSVN
Open Source Contribution Etiquette

Retrieved from "http://wiki.phpbb.com/index.php?title=Git&oldid=8073"

Categories:

Development Wiki

Git

From phpBB Development Wiki

Contents

Basics

phpBB3

Cloning

Branches

Tags

How to contribute?

phpBB4

Repository

Branches

How to contribute?

phpBB2

Repository

Branches

Branch Names

Commit Messages

Developers

Configuration

Hooks

Creating local branches

Workflows

Pulling in upstream changes

Bug fixing

Starting a new feature

Collaborating with other developers on a feature

Merging a feature or bugfix branch

Windows

Create your own SSH key

Clone

Commands

Further reading

External links