Skip to content

Develop from Source

Jump to bottom Edit New page
Andy Pham edited this page Oct 26, 2013 · 24 revisions

If you're a developer who wants to work on the Jupo source code and submit your changes for consideration to be merged into core Jupo code, here's how. Thanks to ThinkUp and Disapora for their awesome developer guide, which inspired ours.

Branching model

Firstly the most important part, the branching model that Jupo follows. Our branching model is based on a post on Git branching models by nvie.

It specifies the following branch structure:

  • master
  • hotfixes
  • release branches
  • develop
  • feature branches

Master

Instead of the master branch being the default bucket where all changes happen, in GitFlow the purpose of this branch is to contain code that’s in a production ready state. You should be able to deploy code from this branch into production at any time and the code in this branch can be tagged with a specific release number to aid that process. This is quite a change for most development teams where 99% of the development happens in the master branch. GitFlow enables you to put a quality gate around the master branch, using workflow, as it requires actual effort to create a release, and then merge that release back into master.

Hotfixes

This branch is a special case for dealing with urgent defects discovered in production post release. The purpose of the branch is that you make a single change to fix the issue (you do not slip other features into this fix as this could introduce other stability issues). This change is then folded into the master branch and also into the develop branch.

Release Branches

This branch is used for gathering features for future release. This branch is also useful for release stabilisation – making changes required to fix issues discovered by any final exploratory testing.

Develop

This is the branch where “general” development activities can occur (rather than on the master branch). This branch can become the general bucket for all changes – but this is really not how it should be used. Any piece of significant work should be done inside a feature branch.

Feature Branches

These branches are for developing an individual feature – this can be dictation by a set of required changes, a backlog item, a bug – essentially any unit of work that needs to be carried out. These branches are short lived – they should not be used for weeks or months on end (otherwise you will incur large integration problems as code on this branch will be out of date compared to all the other work going on).

The easiest way to visualize the pattern is a process flow diagram, showing how changes flow through the development cycle. The arrows signify the creation of or merging of a branch, the dots represent a commit:

Branches

To make following this model easier we use git-flow which contains high level extensions for this Git branching model. Please start by installing the git-flow extensions as per installation instructions on their project page.
There is also some blog posts explaining in short how git-flow basics work:

Please note that the usage of git-flow extensions for Jupo does not stop the usage of vanilla git commands! If you are not able to use git-flow or do not feel comfortable with using it, please feel free to use normal git commands. But we do enforce the branching model so please read the branching model post carefully and follow the guidelines closely.

Figure out what to work on

Maybe you have a feature addition in mind, but if not, check out our issue tracker, our sentry server or come ask on Jupo what needs doing.

Quickfire Do’s and Don’t’s

If you're familiar with git and GitHub, here's the short version of what you need to know. Once you fork and clone the Jupo code:

  • Never, ever, do anything in master branch. The branch develop is the head of development, master is for stable releases!

  • Don't develop on the develop branch. Always create a feature branch specific to the issue you're working on. Name it by issue # and description. For example, if you're working on Issue #359, an aspect naming fix, your feature branch should be called 359-aspect-names. If you decide to work on another issue mid-stream, create a new branch for that issue--don't work on both in one branch.

  • Do not merge the upstream develop with your feature branch; rebase your branch on top of the upstream develop.

  • A single feature branch should represent changes related to a single issue. If you decide to work on another issue, create another feature branch from develop.

  • Keep .gitignore clean. Don’t add test files to .gitignore that are specific to your Jupo setup. Only working config files, dot files, compiled view files, cache files, and logs should be listed in .gitignore.

Commits

  • Do one commit per change. Don't do two unrelated things in the same commit.
  • Put a short, descriptive message on the first line, and then, if necessary, add details in a paragraph after a line break.
  • Always explain why you did something, not how.

Writing good commit messages

Good commit messages serve at least three important purposes:

  • To speed up the reviewing process.
  • To help us write a good release note.
  • To help the future maintainers of Jupo (it could be you!), say five years into the future, to find out why a particular change was made to the code or why a specific feature was added.

Structure your commit message like this:

Summarize clearly in one line what the commit is about

Describe the problem the commit solves or the use
case for a new feature. Justify why you chose
the particular solution.
Do
  • Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Write "fix", "add", "change" instead of "fixed", "added", "changed".
  • Always leave the second line blank.
  • Line break the commit message (to make the commit message readable without having to scroll horizontally).
Don't
  • Don't end the summary line with a period.
Tips
  • If it seems difficult to summarize what your commit does, it may be because it includes several logical changes or bug fixes, and are better split up into several commits using git add -p.

The following blog post has a nice discussion of commit messages: http://who-t.blogspot.com/2009/12/on-commit-messages.html

Coding style

  • Use two spaces for indentation, not tabs.
  • Avoid trailing spaces.
  • Write tests.
  • Clearness over cleverness. It’s better to write a simple, readable method.
  • Avoid long methods. Break them into smaller ones.
  • Write fat models, skinny controllers.
  • If you write migrations, make sure they are revertible.
  • Use english words in the code.
  • Naming convention is important part of making code readable.
    • Name methods and variables according to what they do.
    • Follow python conventions
  • Use private methods for things that are not meant to be used by others.

Naming conventions

For naming conventions, we also follow the guidelines of PEP 8. Some of the existing code doesn't honor this perfectly, but for all new and refactored Jupo code, we'll use:

  • All lowercase module names. Long module names can have words separated by underscores (really_long_module_name.py), but this is not required. Try to use the convention of nearby files.

  • CamelCase for class names.

  • lowercase_with_underscores for methods, functions, variables and attributes.

  • Implementation-specific private methods will use _single_underscore_prefix. Names with a leading double underscore will only be used in special cases, as they makes subclassing difficult (such names are not easily seen by child classes).

  • All JavaScript code should follow these naming conventions as well.

Git workflow step-by-step

  1. Fork on GitHub (click Fork button)
  2. Clone to computer
$ git clone [email protected]:your-user-name/jupo.git
  1. Don't forget to cd into your repo
$ cd jupo/
  1. Set up remote upstream
$ git remote add upstream git://github.com/juposocial/jupo.git
  1. If you use git-flow initialize it
$ git checkout master
$ git flow init -d    # init your git repo with the default settings
$ git checkout develop
  1. Start working on a new issue or feature
$ git flow feature start issue-name
  1. Write code & commit changes to your local issue branch.
$ git add .
$ git commit -m "commit message"
  1. As time passes, the upstream Jupo repository accumulates new commits. Keep your working copy’s develop branch and issue branch up to date by periodically rebasing.
$ git checkout develop
$ git pull --rebase upstream develop
$ git flow feature checkout issue-name
$ git flow feature rebase
  1. Publish feature branch to Github
$ git push origin feature/issue-name
  1. Issue pull request for develop branch In order to make a pull request,
  • Visit the Jupo repository you just pushed to (e.g. https://github.com/your-user-name/jupo)
  • Click Pull Request in the repository header.
  • Pick the branch you wish to have merged using the head branch dropdown
  • Set base repo to juposocial/jupo
  • Set base branch to develop
  • Enter a title and description for your pull request
  • Review the proposed changes using the Commits and Files Changed tabs
  • Click Send pull request.

Once these steps are done, you will soon receive feedback from the Jupo team!

Note! Do not do git flow feature finish for your branch. Submit the whole feature branch as a pull request instead without finishing it. It will be merged to develop by a reviewer.

Note! If you feel this feature should instead be a hotfix, do it still as a feature but mention in the pull request that this pull request would be good as a hotfix directly to master. Don't forget to explain why :)

The perfect pull request

  • It works. The code does what it's supposed to!
  • It works on all of the platforms that Jupo officially supports (Linux of various kinds, Mac & Python 2.6 - 2.7)
  • Handles unicode issues properly
  • Adheres to our coding style
  • Clean & commented
  • Tested
  • Well documented
Add a custom footer
Add a custom sidebar
Clone this wiki locally