Your first pull request

Hello :wave:
Here is a recipe to push your contributions to Collabora Online repository:

If you are not part of the organization over at GH (probably the most common)

  1. Fork the repository forkit
  2. Head over Sign in to GitHub · GitHub and generate or add your SSH key
  3. Clone your forked repo with git clone git@github.com:YOURUSERNAME/online.git
  4. Follow the build instructions
  5. Make sure you have installed commit hook, here is how to do it:
  • ./scripts/refresh-git-hooks
  1. Before starting with your contributions it might be better to make sure your branches of your fork up-are easy sync-able with the upstream:
  • Avoid pressing the button in the GH ui often then not this can result in merge commits polluting your contributions
  • Add upstream repository as your remote:
    git remote add upstream https://github.com/CollaboraOnline/online.git
  • Congrats! From now on to keep your master synced (provided that you do not work on your master) you just need to:
    • fetch git fetch upstream
    • and pull git pull upstream master`
  • To keep your other branches like patch-x you just need to rebase it (and avoid merging) by:
    • Making sure your Fork’s master is up-to-date (with the previous step)
    • And then: git rebase master you will then see Successfully rebased and updated refs/heads/patch-x.
    • Now your branch is up-to-date you can push force whenever you want git push origin patch-x --force
  1. To work on an easy hack switch to a new local branch with git checkout -b patch-x or git checkout -b MyFirstPR etc
  2. Do you changes, rebuild & test etc.
  3. Add your changes with git add . or by specifying the file(s) git add myfile
  4. Commit your changes with signoff git commit --signoff
  5. An editor will open, write your Commit subject and message (see best practices bellow)
  6. Push your new branch to your forked repo git push -u origin MyFirstPR
  7. Go to the online repository and you’ll see a button Compare & pull request, click it.
  8. Click Create pull request

If you are part of the org. over at GH (using g script)

  1. Make sure you GitHubCLI installed
  • Download the right file for your OS at Releases · cli/cli · GitHub
  • on Windows
    • put gh.exe from it locally to c:\users\<username>\bin , so that your Git for Windows can find it.
    • Then from Git Bash please run gh auth login -h github.com -w to login to github interactively
    • Add export USER=yourusername to your bash startup (C:\Users\<your user name>\.bashrc) like so echo export USER=yourusername >> ~/.bashrc
  1. Head over Sign in to GitHub · GitHub and generate or add your SSH key
  2. Clone it
  3. No need to Fork it
  4. Follow the build instructions
  5. (yes you are on master branch, no problem with that, g script will take care, keep reading)
  6. Do you changes, rebuild & test etc.
  7. Commit your changes with signoff git commit --signoff
  8. An editor will open, write your Commit subject and message (see best practices bellow)
  9. Now you can execute g script: ./g review change-xyz (where change-xyz will be a branch)

After this and to clean your local master branch from any change just reset it. Example: you have done one commit and then used the g script, now do git reset HEAD~1 --hard

more info:

9.1 G script
It’s a more practical and fast way to send your changes to GitHub when working on Collabora Online using ‘’‘./g’‘’ [https://github.com/CollaboraOnline/online/blob/a4becf39abc3228fa899f71ff284d41c3c199627/g script]. This will also allow others to collaborate with you within the same pull request.

Collabora Online now has a ./g script that tries to bring some of the Gerrit-based review benefits to a workflow based on GitHub. Motivation

Collabora Online is on GitHub, but core.git is still on Gerrit, so it made sense to spend some time on a small shell script that gives you review and backport experience that is closer to Gerrit than the stock GitHub workflow.

from : Miklos blog post

9.2 Workflow example: working without manually creating branches

  • Checkout upstream branch (for example “distro/collabora/co-6-4” )
  • Do your changes
  • Run: ./g review change-xyz
  • this will
    • Create a branch off “distro/collabora/co-6-4” (/private/lpranam/change-xyz)
    • Start a pull-request automatically
    • Show the url in your terminal
  • you can then reset you main local branch to proceed into another change
    git reset HEAD~n --hard

You can also add more commit into that PR (e.g.: #1234) by running:

  • gh pr checkout 1234
  • Apply changes , add commit and then push to add that commit or in the case you want to rewrite it:
  • git push origin /private/yourghusername/change-xyz --force

9.3 Workflow example: working from different local branches
Added by Mike in Use custom local branch name as explicit…

If you prefer to work on your local branch (and that name is different from the tracked branch name), it is treated as if user used that name explicitly. So:

  • git checkout -b featureFoo origin/master
  • git checkout -b featureBar origin/distro/collabora/co-6-4
  • [ … ]
  • git checkout featureFoo
  • [ edit session ]
  • git commit
  • ./g review # this uses “featureFoo” as implicit second argument
  • git checkout featureBar
  • [ edit session ]
  • git commit
  • ./g review # this uses “featureBar” as implicit second argument

so no need to remember which PR name was used where.
This only works for local branch names that are not equal to a remote
branch name, or to the last part (after last /) of any distro branch.


If you are part of the org. over at GH (without using g script)

  1. Head over Sign in to GitHub · GitHub and generate or add your SSH key
  2. Clone it
  3. No need to Fork it
  4. Follow the build instructions
  5. Switch to a new local branch with git checkout -b private/yourusername/MyFirstPR
  6. Do you changes, rebuild & test etc.
  7. Commit your changes with signoff git commit --signoff
  8. An editor will open, write your Commit subject and message (see best practices bellow)
  9. Push your new branch to the organization repo git push -u origin private/yourusername/MyFirstPR
  10. Go to the online repository and you’ll see a button Compare & pull request, click it.
  11. Click Create pull request

Best practices for git commit messages
In general, read [How to Write a Git Commit Message How to Write a Git Commit Message] by Chris Beams.

  • The commit message should tell what the commit does, in imperative mood. If necessary, you can mention how the code used to work, too. But what actually is done by the commit should be in present tense. Not what you did. Not "Fixed hang in foo()" but "Fix hang in foo()"
  • The first line should be clearly less than 80 characters. It is supposed to be a minimal summary. It can be called the subject of the commit. Do not end it with a period.
  • If the change is very simple conceptually, that one line might be enough.
  • The rest of the commit message describes the change in greater detail. This is the body of this commit message. The body is written after the subject line with one blank line in between. The blank line is used by various tools (such as 'git log', 'git show', etc.) to differentiate subject from body. Further paragraphs are also separated by blank lines.
  • Explain the problem being solved by this commit. More importantly, '''explain ''why'' these changes are being made''', as opposed to ''how''. The 'why' part is your responsibility, the 'how' part is code's responsibility.
1 Like

Thanks Pedro,

As I didn’t build COOL (Step 4), my step 4 is:
4. ./scripts/refresh-git-hooks than cp .git-hooks/commit-msg .git/hooks/commit-msg

I have turn this into a wiki post (so everyone can edit)