What is the difference / relationship between GitHub Projects and Milestones?

Question

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.

My opinion:

• A Project is about a process and the people.
• A Milestone is about a product.

A Project is best for getting insight into a process used by the people in the group. A better name for it would be "workflow" or "process". There's more overhead involved in creating a new project vs. creating a new Milestone. So you really only want to create a new Project when there's a new process in your team: Lanes must be chosen, configured, and ordered. They can also be very different in each Project. I think back to the original use of Kanban by Toyota: managing the people and their workload.

A Project answers the question, "What are we working on at the moment?"

Two great Project examples: software development and blogging. The configurations for each would support the different groups' people processes; how they work together and sign off on things.

Milestones, in contrast, all work the same. They're an ordered list of tasks which must all be closed for the work product to be considered complete. Optionally, a due date can be set, which just provides reminders, but does not change the Milestone functioning.

A milestone answers the question, "What is remaining to finish this product?"

Milestones are kind of labels that mark and group tickets that are expected to be delivered at some point in time. The Milestones page which you can access from Issues page makes it clear - you can see the percentage of tickets completed for a particular milestone and the due date. You can also sort milestones by due date and prioritise tickets within a particular milestone.

The stress here is on delivery dates and tracking progress.

Projects on the other hand are implemented in GitHub as Kanban boards with some bells and whistles. You can specify a number of columns (and swimlanes - as @Doug said below swimlanes are not supported yet) to create simple workflows. You can then add tickets from one or many repositories, prioritise them, and then progress them from one column to another as they are being worked on. You could, for example, have 'Backlog', 'In Progress', 'Under Review', 'In Testing', and 'Done' columns and move tickets from left to right, or from right to left if, say, a defective ticket gets bounced from 'In Testing' back to 'Backlog'.

The stress here is on organising and managing the work.

Then how you organise and partition that work is up to you. You could create a project per milestone or have several milestones in a single project, or split milestones into shorter sprints. You could also have several projects covering different aspects of working on the product, for example, one for developers and one for testers.

One nice thing about projects is that they're more free-form than milestones. You can just chuck notes in them and link to issues, and organise them however it suits you. They're great for jotting down ideas, making roadmaps, and listing resources and dependencies. In the past I've used issues and the wiki for the same things, but I found both to be too formal and transactional (i.e. higher overhead).

On GitHub:

• The Project is a process that has beginning but no ending.
• The Milestone is a process that emphasizes the end time.

So it is correct to use milestones to split the project into many stage with end times.

I use it like this:

• Organization Project is used to organize the process that about multiple repositories.
• Repository Project is used to organize the iterative process of long-term branches, such as develop branch, custom branch.
• Milestone is a iteration stage.