Github – the difference / relationship between GitHub Projects and Milestones

githubproject

The recent update to GitHub added something called Projects into the GitHub workflow, and because I don't have any particular experience with project tracking tools such as Jira or Trello (hey, at least I noticed the similarity), could anyone, please, elaborate on the (key) differences between GitHub's Milestones and the new Projects?

If I understand correctly, Milestones are a way of organizing issues into smaller "sub-projects" – smaller than the whole "project" (which, in my world view, is represented by the repository). When all issues are done/closed, the milestone can be regarded as complete.

The newly introduced Projects are also, as I see it, a way of organizing issues into smaller-than-the-repository "sub-projects" (albeit called Projects). I understand the workflow is supposed to be slightly different and more fine-grained than with "mere" Milestones.

So, are Projects something that supplements Milestones (or rather Milestones supplement Projects now?) or should I rather view Projects as a replacement of Milestones?

Where exactly do the Projects actually fall into the repository[-milestone]-issue hierarchy?

Sadly, GitHub's blog entry about the introduction of the Projects doesn't mention any relationship (https://github.com/blog/2256-a-whole-new-github-universe-announcing-new-tools-forums-and-features).

I somehow feel there is one, but I can't put a finger on it.

Best Answer

I'm wondering the exact same thing. Here is what I came up with.

First, let's review the main similarities and differences:

An issue can belong to multiple Projects, but only one Milestone.
~~Projects are never complete. There is no progress bar, or deadline.~~ Projects ~~have no progress bar or deadline~~ (they do now, though it is hidden inside the project's menu as a "Track project progress" checkmark, and there's no percentage calculation of progress), but can now be closed (as pointed out by @Sheen)
Milestones on the other hand have all that, but lack any form of organization. An issue is either in a milestone, or isn't. (They can be ordered as pointed out by @Nick McCurdy)
~~Issues can be filtered by Milestone, but not by Project.~~ As pointed out by @cmonkey, issues can now be filtered by Project as well as Milestone.
Projects can contain Notes (which can be converted as issues) so it doesn't pollute the issue tracker with vague ideas
A Project can span over multiple Milestones, and a Milestone can contains parts of different Projects.
An Organization can have Projects as well. These projects can include tickets from any repository in the organization, which makes it quite useful.

So the way I see it, is that Projects are a completely separate way to visualize and organize your work on an higher level (think "project management", multiple teams, multiple repository, etc.), while Milestones are a way to organize your deadlines and releases on a more basic level (think "release management", "versions", etc.). With this in mind, it makes sense that an issue only belongs to one Milestone (it's only released or pushed to production once) but can be part of different Projects.

I'm sure they are other ways to look at it though, and I'm interested to hear other opinions.

Edit December 2017

Some time ago, after working with Milestones and Projects for over a year, I realized there is another important aspect I had completely overlooked.

Milestones is a tool for Scrum methodology. Milestones are good for timeboxed iterations and working in sprints with batches of issues.
Projects is a tool for Kanban methodology. Projects are good for continuous delivery and steady flow of work.

Related Solutions

Git – Link to the issue number on GitHub within a commit message

Just include #xxx in your commit message to reference an issue without closing it.

With new GitHub issues 2.0 you can use these synonyms to reference an issue and close it (in your commit message):

fix #xxx
fixes #xxx
fixed #xxx
close #xxx
closes #xxx
closed #xxx
resolve #xxx
resolves #xxx
resolved #xxx

You can also substitute #xxx with gh-xxx.

Referencing and closing issues across repos also works:

fixes user/repo#xxx

Check out the documentation available in their Help section.

Git – Multiple GitHub accounts on the same computer

All you need to do is configure your SSH setup with multiple SSH keypairs.

This link is easy to follow (Thanks Eric): http://code.tutsplus.com/tutorials/quick-tip-how-to-work-with-github-and-multiple-accounts--net-22574
Generating SSH keys (Win/msysgit) https://help.github.com/articles/generating-an-ssh-key/

Relevant steps from the first link:

Generate an SSH-key ssh-keygen -t rsa -C "john@doe.com", follow the prompts and decide a name, e.g. id_rsa_doe_company.
Copy the SSH public-key to GitHub from ~/.ssh/id_rsa_doe_company.pub and tell ssh about the key: ssh-add ~/.ssh/id_rsa_doe_company.

Create a config file in ~/.ssh with the following contents:

Host github-doe-company
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa_doe_company

Add your remote git remote add origin git@github-doe-company:username/repo.git or change using git remote set-url origin git@github-doe-company:username/repo.git

Also, if you're working with multiple repositories using different personas, you need to make sure that your individual repositories have the user settings overridden accordingly:

Setting user name, email and GitHub token – Overriding settings for individual repos https://help.github.com/articles/setting-your-commit-email-address-in-git/

Hope this helps.

Note: Some of you may require different emails to be used for different repositories, from git 2.13 you can set the email on a directory basis by editing the global config file found at: ~/.gitconfig using conditionals like so:

[user]
    name = Pavan Kataria
    email = defaultemail@gmail.com

[includeIf "gitdir:~/work/"]
    path = ~/work/.gitconfig

And then your work specific config ~/work/.gitconfig would look like this:

[user]
    email = pavan.kataria@company.tld

Thank you @alexg for informing me of this in the comments.

Best Answer

Edit December 2017

Related Solutions

Git – Link to the issue number on GitHub within a commit message

Git – Multiple GitHub accounts on the same computer

Related Topic