Filing Issues

Filing Issues

Issues for Crossref-managed properties and applications should be filed into GitLab. GitLab issues replace both Jira tickets and GitHub issues.

GitLab issues must be filed into a specific GitLab project within the Crossref group. Defects (bugs) for specific applications should be filed into that application’s project. Feature requests should be filed into the user_stories project. All other issues, including reporting requests, questions, and developer tasks should be filed into the Issues project.

If you’re not sure where to file an issue, file it to the Issues project and the triage committee will route it to the appropriate project.

How to write a good issue

Include as much information as you can when drafting an issue. The triage and Backlog Refinement processes will refine an issue before it is picked up by a developer, so don’t worry about getting everything perfect.

Be careful not to include personally identifiable information in an issue, as GitLab issues are publicly accessible (more on that below).

When reporting a defect, first search for an existing issue reporting the same defect. If an issue already exists, add your instance as a comment to that issue. When filing a new issue or adding to an existing issue, please include as much of the following as possible:

  • Steps to reproduce
  • Expected behavior
  • Observed behavior
  • Screenshots
  • Example submission IDs
  • Example XML
  • Example queries
  • Error messages
  • Console logs
  • OS, browser and version
  • Your assessment of severity/urgency

The proper way to assign priority is via the priority labels (eg priority::1, priority:2). While product owners or tech leads may adjust the priority assigned to issues, feel free to assign an initial prioritization based on your understanding of the issue. This will help us rank this issue against everything else we have queued up for development. Issues may be assigned a priority between P0 and P4:

  • priority::0 - Urgent issues requiring immediate attention, likely displacing other in progress work
  • priority::1 - High priority issues to be brought into a sprint soon
  • priority::2 - High/medium priority issues (issues associated with top organizational priorities are assigned a P1 or a P2 in most cases)
  • priority::3 - Low priority issues
  • priority::4 - Lowest priority issues, unlikely to be brought into a sprint unless circumstances change

For some P4s, if an issue is unlikely to be prioritized into a sprint within the next 6 months, we may simply close the issue. However, it is still useful to record an issue in case we need to reference it in the future.

When filing a feature request into the user_stories, issues, and other projects, you’ll notice issue descriptions start with a template. Please follow the template whenever possible, and include a thorough description of what you’re asking for and why.

Prior to developing new features, we aim to consider the impacts there might be on other aspects of the business. While product managers and stakeholders are responsible for thinking through all of the knock-on effects of our work, any information you can provide on the following topics will help us maintain a healthy software development process:

  • Billing/costs
  • Internal documentation
  • External documentation
  • Schema
  • Metadata Outputs
  • Operations
  • Support & Membership experience
  • Outreach & Communications
  • Testing
  • Internationalization
  • Accessibility
  • Metrics, analytics, reporting

GitLab features a number of controlled fields for issues, including Milestones, Due dates, Labels, Weights, and Confidentiality. We’re consistently evaluating how best to use a number of these fields, but please note that Milestones and Weights are used for sprint management. Any information provided in these fields will likely be replaced during Backlog Refinement. If your issue is time-sensitive, please let us know in the issue description.


All new GitLab issues will be triaged a few times per week, typically Tuesdays and Thursdays, by available members of the scrum team.

Triage is intended to cast a wide net, reviewing all newly filed issues regardless of project. Issues will typically be routed into a few different queues, as appropriate:

  • Planning::Backlog - Preferably with Service:: and Priority:: labels to help us keep things organized
  • Planning::Needs Definition - high priority or otherwise timely issues that should go into Backlog Refinement to be prepared for an upcoming sprint
  • Planning::Support - questions from the general public requiring a support response
  • Planning::Product - feature requests for consideration by the product team, though most issues should go straight to Backlog or Needs Definition.
  • Planning::Sprint - urgent issues may be fast-tracked into the current sprint
  • Planning::Out of scope - some GitLab issues may be out of scope for the development workflow, eg Strategic decisions register issues

Please note that under normal circumstances, issues will need to be reviewed and slotted into an upcoming sprint. If an issue represents something requiring urgent attention, please say so in the issue, and we’ll aim to bring it into the current sprint. If an issue is so urgent that it cannot wait for our daily triage, please file an issue and raise it in the #operations Slack channel.

Backlog Refinement and Estimation

High priority issues will be reviewed in more detail by the Backlog Refinement team (typically, those developers, product owners, and support staff who are available). During Backlog Refinement, issues will be prepared to meet our definition of ready, estimated, and prioritized into upcoming sprints.

To propose an issue for refinement, make sure it has the “Planning::Needs Definition” label and the Milestone for the next sprint (which should be appended with “(next)” to make it easy to find). Ideally the description and, more importantly, acceptance criteria will be drafted ahead of refinement so we can efficiently work through issues.

Backlog Refinement will typically take place three times per sprint on Tuesdays and Thursdays, skipping days on which we have Sprint Planning.

The last refinement session of a sprint typically includes an estimation exercise, where we will collectively assign story points to issues based on their relative complexity. This exercise helps surface any remaining misunderstandings or disagreements about the work to be done and provides a facility for sizing issues. After tracking story points for a few sprints we now have a rough idea of how much work we can get done in a typical sprint. Over time, we’ll improve our ability to forecast when various bits of work are likely to be delivered.

GitLab issues are public

GitLab issues are accessible to the public by default. We hope this allows us to more tightly align our development work with our community’s needs.

Please keep this in mind when writing and commenting on issues. Snark, sarcasm, or other creative tones of voice should be avoided.

Sometimes issues must include personally identifiable information, sensitive information like machine addresses or passwords, or other information we need to keep confidential. In these cases, individual issues can be marked as confidential, preferably when the issue is drafted by checking the box below the issue description, or after an issue is created by clicking “edit” under the Confidentiality section of the sidebar on the right, then clicking “Turn On.”

Tips and tricks

  • Looking for a list of issues you filed? Click the search box at the top of any page, then click Issues I've created. From there, you probably want to sort by last updated or date created to find issues you’ve worked on recently.
  • When searching for issues, you may find it easier to search from this list view, which is unconstrained by project and should search for all issues within the Crossref group, as opposed to the field labeled “Search or jump to…” in the page header, which returns search results for other areas of GitLab as well.
  • Clicking a label on an issue in the results view will apply that filter as a label, but will also constrain your search to the project of the issue you clicked. Beware that you are no longer searching globally until you return to this list view.
  • Filters are joined with an and by default.
  • Note that only Open issues are returned by default in the aforementioned list view. You can select tabs for “Closed” and “All” issues if you prefer.
  • Bulk edits from the list view are possible, but only for one page of results at a time.