Issue management on Github

Schema.org uses GitHub for collaboration. We have both a GitHub repository for the project, as well as an issue tracker. This page gives some overview of how we are using our GitHub issue tracker.

Anyone (once they have created an account) can open a schema.org GitHub issue, or comment on an existing issue. Issues can be tagged with one or more labels, and will be either marked “open” or “closed”.

Open vs Closed status

Due to the broad scope of schema.org – descriptions of things that are commonly mentioned in Web pages – we receive a great many valuable suggestions for potential improvements. Over time these have accumulated and at the time of writing there are over 400 open issues (and over 450 that we have closed). We are moving towards a process in which it will be more common for issues to be marked as closed. This page serves to document more clearly what ‘closed’ means in the context of the schema.org project.

Issues are marked “open” in several situations:

• They have just been filed or have not been reviewed.
• They propose vocabulary in an area where work is likely or ongoing, or which looks like a simple easy addition.
• They propose tooling / infrastructure improvements to the site that is likely, ongoing or easy.
• The correspond to a vocabulary-proposing issue for which we have published an exploratory implementation at pending.schema.org.
• They raise a technical or tooling issue.

Issues may be marked as “closed” in situations where:

• The issue, problem or question they raise has been addressed.
• The issue isn’t one we can usefully help with.
• The raised issue outlined is noted (via Issue #2) as a sensible or good vocabulary idea but which will need attention later as part of a larger cluster of work.
• The raised issue outlined is noted (via Issue #3) as a sensible or good tooling / site infrastructure idea but which will need attention later as part of a larger cluster of work.

This structure means that many good ideas will be marked as “closed”. This status should not discourage discussion, it is just our way of coping with a potentially endless stream of schema suggestions. Schema.org’s scope is as open-ended as Web search; this means we have to prioritize, balancing “quick fixes” with high impact but complex design discussions. Our mechanism for handling an ever growing collection of vocabulary proposals is to make sure that they are labelled, noted from our top level tracking issue (#2), and that it is clear that “closed” does not mean “will never be addressed”.

The overview issue (plus GitHub’s search facilities) provide discovery mechanisms for closed issues.

Issue labels and status changes

Issues are most commonly closed by the community group chair / webmaster, but also sometimes by those in the project steering group and wider community who have been leading discussions in a particular area.

Prioritization

We have historically attempted more explicit issue prioritization. It has proved difficult to predict when the right combination of people’s time/attention and consensus will combine to produce results. For earlier releases, we allocated issues to release-oriented Milestones, but this was not very successful. Currently the best view of priorities comes via a per-release issue in which the community discuss which areas are nearing consensus. These are always linked from the entry point issue, conveniently numbered Issue #1.

At the present time (August 2016), a meta-priority is to get our open issue list down to a manageable level. Roughly this is to have < 100 open vocabulary issues, and < 50 open infrastructure/tooling issues.