Forking and Contributing to Mondrian

This is a description of how to integrate git and GitHub into your Pentaho Mondrian development workflow, as well as criteria and settings specific to developing with Mondrian. It can also help people new to git get used to how the basic concepts work and what the common workflow will look like with git.

Forking to your account

The first thing you need to do is fork the Pentaho repository into your GitHub account. This creates an exact copy of the Pentaho repo as it exists at the time of the fork in your personal GitHub space. This copy is not updated as the Pentaho repository gets updated, but we’ll cover how to keep it updated later.

From the Mondrian repository page click the Fork button near the top right:

Once you have done this, GitHub will redirect you to your newly forked repository.

Cloning a specific branch

Mondrian works on a single repository with multiple branches containing the different versions – past, released and in development. You should never be working against the master branch without permission from the Mondrian development team. Always work against the repository specific to the version you are developing for. Cloning the repository moves all the data and metadata from all branches to your local working folder, and you then checkout a specific branch locally to setup the file structure for that version.

First, clone the repository:

$ git clone [email protected]:[username]/mondrian.git

Cloning into 'mondrian'...
remote: Counting objects: 51661, done.
remote: Compressing objects: 100% (9979/9979), done.
remote: Total 51661 (delta 37833), reused 51512 (delta 37691)
Receiving objects: 100% (51661/51661), 294.25 MiB | 604 KiB/s, done.
Resolving deltas: 100% (37833/37833), done.

Now change into the newly created ‘mondrian’ folder and list the available branches:

$ git branch -a

  master
  remotes/origin/3.0
  remotes/origin/3.1
  remotes/origin/3.2
  remotes/origin/3.2.2
  remotes/origin/3.3.1
  remotes/origin/3.4
  remotes/origin/HEAD -> origin/master
  remotes/origin/lagunitas
  remotes/origin/master
  remotes/origin/pacino

And finally checkout the branch you want to work on:

$ git checkout 3.4

Branch 3.4 set up to track remote branch 3.4 from origin.
Switched to a new branch '3.4'

Adding upstream and local settings

In order to be able to keep your repository up-to-date with the Pentaho Mondrian repository, and to be able to merge your changes with changes made while you were developing your feature, we will add a new remote called ‘upstream’ that will point to the Pentaho repository directly.

$ git remote add upstream git://github.com/pentaho/mondrian.git

You also want to disable fast-forward during merges to preserve the entire commit history and properly track file changes.

$ git config --add merge.ff false

Note: If you have a git version prior to 1.7.6, this option will do nothing.

Your repository is now ready to develop against your selected branch.

Merging upstream changes

It is important during development that you keep your repository updated with any changes made to the Pentaho Mondrian repository. This not only ensures that your are always working with the most recent code available for your working branch, but also ensures that your changes do not break any new or updated tests.

To update and merge changes from the upstream repository, do the following:

$ git fetch upstream [branch]
$ git merge upstream/[branch]

Where [branch] is the current branch you’re working on.

If you are using a version of git prior to 1.7.6, you need to add the —no-ff flag in order to disable fast-forward merges:

$ git merge --no-ff upstream/[branch]

If there are any merge conflicts, git will let you know. Otherwise, your local repository is now up-to-date without losing any of your working changes.

This should always be the 2nd last step performed before issuing a pull request. The last step being, of course, running the tests again after the merge to ensure nothing is broken.

Verifying the coding style

The Mondrian project require that all contributions conform to the coding style that we have pre-defined. To verify that your contribution conforms to those standards, you can use the checkFile utility. From the project’s root folder you must run and fix all the problems reported by the following command:

$ ./bin/checkFile.sh --under [folder where you made some changes, probably "./src"]

Generating a Pull Request

A pull request is the way GitHub manages the process of merging changes between forked repositories. Generating a pull request starts a conversation with the Pentaho Mondrian development team asking them to review the changes you’ve made, comment on them, and optionally choose to merge the changes into the main repository or return them to you for additional changes.

Before starting a pull request, please make sure the following criteria are met or your request may not be accepted and merged, or may take much longer to be merged into the Pentaho Mondrian repository.

• At least one test case for the feature itself
• At least a test case for failures and errors
• It doesn’t break any other tests

When you are ready to start a pull request, go to your personal Mondrian fork on GitHub and select the branch you want to be marged. Then click the Pull Request button near the top of the page.

You can then fill in a title and notes related to the pull request, and click the Send pull request button. The Mondrian development team will be notified of the pull request and will continue the process from there.

For a more detailed description of the entire pull request and commenting process, see Help.GitHub – Send pull requests