What are issues for?

Issues and milestones are public-facing entities, yet their content can be highly technical to serve as a roadmap and implementation guide for developers. As we see it, the various audiences for issues and milestones, and their needs, are as follows:

Using these conventions gives rise to a workflow where new issues come in with no assignee and no milestone, and the project maintainers either assign them to a developer who will carry out the work, or put the issue in "unscheduled" with no assignee.

As issues are closed, they are sorted into milestones which match each project's release tags, making it easy to browse which issues were addressed as part of each release.

The high-level topics of interest (i.e., bugs and enhancements) can easily be filtered by label, while milestones establish the timeline and functional development.

Note that the relationship between milestones and software releases can be one-to-many: e.g., bug-fix releases, or even the addition of new features, may not necessitate their own milestones. Good milestone structure should read similarly to a good githistory: informative without being overly verbose.

Citable code

Many of these tools are employed to facilitate reproducibility from a technical perspective. From a social perspective, we are writing software for science - in which scholarly citations provide another currency for reproducibility.