Public Lab Research note


Use Git and GitHub to contribute and improve Public Lab software

by warren , bsugar | November 22, 2017 20:09 22 Nov 20:09 | #15228 | #15228

Public Lab software is written in many languages, and each project may have its own guidelines for contributors. These broad guidelines should serve as general principles to guide your approach to a new Public Lab codebase, using Git and the collaborative coding website GitHub.

Our welcoming page for new contributors is here: https://publiclab.github.io/community-toolbox/ -- please check it out!

Contributing using git

Check out this article on GitHub Flow, a routine that works great on all git projects and makes Public Lab development super smooth.

image description

A sample git workflow

Let's say that a developer and PublicLab community member named Susan decides that she wants to add a feature to plots2 (PublicLab.org). Here's what Susan's workflow might look like:

  1. Susan forks the publiclab/plots2 repo on GitHub.
  2. Susan clones the forked repository susan/plots2. This downloads a copy of Susan's version of plots2 to her computer.
  3. She creates a branch for the new feature (a feature branch). Let's say that Susan wanted users to be able to tag maps. She might then create and checkout a new branch called add-map-tags with: git checkout -b add-map-tags.
  4. Susan develops the new feature in the add-map-tags feature branch, making commits (and running tests) as she goes.
  5. When Susan is done developing the new feature, she switches back to the master branch of her own repository: git checkout main, and then pulls the latest version of plots2 down from the publiclab repo with git pull https://github.com/publiclab/plots2.git main.
  6. Susan applies her new feature on top of the latest version of plots2: From the add-map-tags branch, she runs git rebase main. This is the great strength of doing development in a feature branch - it allows Susan to merge her changes into the latest public version of plots2 on her own computer and to resolve any conflicts locally.
  7. After rebasing, Susan's local feature branch add-map-tags contains the latest version of plots2 with her new feature added on top. The new feature is ready, so Susan pushes her feature branch up to her own remote repository with git push origin add-map-tags and submits a pull request on GitHub from that to publiclab's master branch.
  8. Susan discusses her code with others. After any questions or change requests have been resolved, Susan's request is merged in, and her contribution becomes part of PublicLab.org!

Best practices

A few notes - some git best practices that will make all of our lives easier:

  • Remember to pull from main before you start working on a new feature. This helps keep your local repository in sync with the code that everyone else is working on. If you've forgotten to, see below for how to recover without losing your work.
  • Always do development in a feature branch (again, see below if you've forgotten). This makes it much easier for project maintainers to merge your contributions into the trunk. The name of your branch is displayed when it is merged in to the main trunk, which means that it serves as built-in documentation for your feature. This works great when you give your feature branches descriptive names! Some example branch names:
    • donation-button-redesign
    • markdown-package-update
    • fix#44 (fixes GitHub issue #44 in this repository)
  • Open a pull request early! In fact, feel free to open a pull request as soon as you start working on a new feature or bugfix. GitHub's pull request pages make it easy to see progress that's been made on an issue, and it's a great way to start an open and ongoing discussion with the project's maintainers and other contributors about your work.

For some additional tips for different scenarios, such as if you've forgotten to make your commits in a named feature branch and need to rewind your master, see Additional Workflows on this page

We're happy to help! Please feel free to ask questions here, or at https://publiclab.org/wiki/developers


I did this Help out by offering feedback!


People who did this (0)

None yet. Be the first to post one!


6 Comments

@warren, I didn't get a chance to run this activity yet, but I will because my next commit will be from the terminal. In the meantime, can I suggest that the tutorial by @liz "How to make the most basic github contribution" be elevated to the top of this activity with some text such as "If you'd prefer not to use the terminal, you can also learn how to make changes in the browser here."

Reply to this comment...


@liz has marked @bsugar as a co-author.

Reply to this comment...


Awesome, thanks @liz!

Reply to this comment...


@warren, Liz made me a co-author, but at the time the change I wanted to make wasn't related to your instructions for the terminal.

I'd like to propose a change which is to add something to step 7.

Context: I had already pushed some commits and made a pull request after which I needed to make some more changes and push additional commits. I re-followed your instructions which work perfectly except when you get to git push origin add-map-tags.

At this point I got the following error:

needs to be git push -f origin add-map-tags. If I just do the former I get the following error: ! [rejected] my-branch -> my-branch (non-fast-forward) error: failed to push some refs to 'git@github.com:user/plots2.git' hint: Updates were rejected because the tip of your current branch is behind hint: its remote counterpart. Integrate the remote changes (e.g. hint: 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details. The solution detailed here of git push -f origin my-branch worked. It seems like given the original S.O. question, this is because it was not my first push anymore?

Proposed change:

Assuming that is the reason, add something to the effect of (in bold italics):

After rebasing, Susan's local feature branch add-map-tags contains the latest version of plots2 with her new feature added on top. The new feature is ready If this is Susan's first time pushing to this remote repository she will use git push origin add-map-tags. If Susan has previously pushed to this repository she will add -f to the command like so, git push origin add-map-tags. Susan then submits a pull request on GitHub from that to publiclab's master branch.

Is this a question? Click here to post it to the Questions page.

Reply to this comment...


Hi @warren @bsugar great piece, thanks...a lot of new contributors do use this for guidance...with the renaming of our base branches from master to main it been a little confusing and a contributor reached out asking if we could update this too. Thanks again

Sorry Cess I must've missed this email. Yes let's change it for sure.

Ok, done!


Reply to this comment...


Login to comment.