Joomla! Documentation™

Joomla GSoC Github Flow

This document contains guidelines for GSoC students and mentors on how to manage and work with Github Repo's for GSoC projects. All the Repository's for GSoC projects are available on Joomla! Project Github

Joomla! GSoC Student Workflow

First step is forking your joomla-projects/gsoc16_** repository to your personal GitHub account. Never make changes to the joomla-projects repository directly. Any contributor should work on his/her own fork of it, and move code to central repository using pull requests. Also, nobody should ever merge her/his own PR. Students should always work on branches, they should never make changes to their staging branch!

Preparation

On Github, navigate to the joomla-projects/my-gsoc-project repository and click on the ‘Fork’ button in the upper right corner. This creates a fork (a linked copy) in your account (let’s call it ‘my-user’), resulting in a new repo my-user/my-gsoc-project.

Next step is cloning the forked repository to your local computer. If you set up ssh-keys in GitHub (recommended), use the link with ssh. If not use the https link.

git clone -b staging git@github.com:my-user/my-gsoc-project.git

To keep your fork updated with the changes from joomla-projects, you need to add the joomla-projects repo as additional remote repository (mostly called upstream):

git remote add upstream https://github.com/joomla-projects/gsoc16**

You can now update staging by applying the following command:

git fetch upstream staging

Next merge the changes:

git merge upstream/staging

And push them to your remote fork

git push

Your mentors are going to keep the joomla-projects repository in sync with joomla/joomla-cms staging. You need to do the same for your fork!

Making a pull request with your changes

Now you can start working on your local computer. The project folder is under version control, so you can follow any changes you make. Always make a custom branch for your changes and do not work on staging directly.

git checkout -b patch-name

When your patch is ready you send a so called Pull Request (PR) from your repository to the joomla-projects one.

For that you have to push your changes to your forked repository. First make sure there are no unnecessary files and comments left. And that your code is probably formatted according to the Joomla! Code styles.

git status

and

git diff path/to/file

are going to help you with that. Next add all files you want to include in your PR with:

git add path/to/folder/or/file

After that you need to commit your changes and push them to your fork:

git commit -m “Describe your changes as best and short as possible here”

Push the changes to the repository

git push

For pushing a branch to GitHub you would use the first time:

git push origin BRANCHNAME

Go the GitHub website and open your forks site. You are going to notice that there is a notice about your recent push at the top:

Click on ‘Compare & Pull request‘. Add a meaningful description, including summary of changes and important (!) testing instructions and click on ‘Create pull request‘.

Now wait to for your Mentors comments, if everything is working they are going to merge your PR into the joomla-project repository. If not you can just fix it locally and push again. The PR is going to be updated automatically with these changes.

Keeping the GSoC fork updated with Joomla staging (For Mentors)

Preparation

In your dev environment clone your own (forked) repository. my-user/my-gsoc-project is automatically added as 'origin'.

git clone -b staging git@github.com:my-user/my-gsoc-project.git

Next we add the joomla-projects/gsoc16** repository as upstream and the joomla/joomla-cms repository as joomla remote.

git remote add upstream https://github.com/joomla-projects/gsoc*.git

git remote add joomla https://github.com/joomla/joomla-cms.git

Never change the staging branch! It is a verbatim copy from the joomla/joomla-cms repo, and must be kept in sync by you. You can set the branch to protected so that only mentors are allowed to push to it.

Update staging

Whenever something changes in the CMS repo, the staging branch needs to be synchronised.

Checkout (activate) current staging branch

git checkout staging

Next get the changes from the joomla/joomla-cms staging branch

git fetch joomla staging

Merge the changes

git merge joomla/staging

Push the changes to your own repository and to the joomla-projects/gsoc one.

git push origin staging

git push upstream staging

Update feature branches

With all of your feature branches, the changes have to be merged as well.

Checkout the branch first:

git checkout branch-name

Merge changes from staging

git merge staging

There might be conflicts, when the CMS changed code, that was changed in your feature branch; in that case, consult `git merge --help`.

Tips and tricks

Before making any changes create a new branch, so you can easily update your forks staging (or master) later and make multiple pull requests for one Repo.

git checkout -b NAME

Keep your pull requests as small as possible. This makes testing and getting them merged far easier. Be descriptive in your pull request. Explain step by step how to test the changes. Where possible add screenshots for clarification.

Code style:

Please make sure you don’t leave any unnecessary files, comments (don’t comment code!) in your PR. Also make sure it matches the Joomla! Coding style guidelines.

Contributing to the Joomla! CMS™

Joomla! Coding Standards Manual