Skip to content
GitStart's Documentation
GitHubTwitter

How to write better tickets

Well-scoped tickets are crucial to GitStart shipping quality pull requests under a reasonable timeframe.

When tickets are clear and well-defined, we can deliver PRs with the highest quality and in the quickest time possible. On the flip side, poorly scoped tickets can cause delays and longer review cycles, and we definitely want to avoid that!

So, how can you write better tickets?

Reduce uncertainty

We prefer not to make assumptions about what you want, because assumptions lead to mistakes and misundertandings.

  • Set clear acceptance criteria. This should answer the question: How do I know that the task is complete? The ticket should describe a clear problem definition and a required solution.
  • State assumptions that might not be obvious. This is especially true for business and user requirements and edge cases.
  • Provide resources required to complete the ticket. Depending on your ticket, this includes things like:
    • design files
    • environmental variables
    • credentials to access resources if applicable (e.g., Firebase ID, TestFlight, cloud providers)
    • a replica of the staging environment to test the pull requests.
    • a container environment for testing the code locally
    • prganizational licenses for mobile deployment testing
    • a sample database to test locally
    • a list of critical CI checks to replicate and pass. Inform GitStart of any change in the CI workflows, especially when CI tools are not GitHub Actions.
  • Provide guides that can help delivery. This includes references to internal documentation, similar issues, existing utilities, and previous implementation examples.
  • Provide exhaustive criteria for GitStart to generate test cases for both functional and code testing. The easiest thing to do is to add bullet points of what should be in place for the ticket to succeed.
  • Assign tickets not blocked by external dependencies. If tickets are linked to one another, it’s more likely to delay the release.

Break it down

Reduce the scope by breaking it down into smaller tickets.

A ticket should solve only one problem. If a ticket consists of more than one problem-solution description, it shows that the ticket is bigger than it was supposed to be and can be broken down into pieces. One problem-solution example: “Build a button component with three different states”

For example, a feature ticket could be broken down into frontend and backend tickets. Similarly, a backend ticket can be broken down when multiple solutions can be executed in parallel and in isolation.

A ticket is sufficiently small if it takes less than five working days to complete, including testing and providing you with proof that it works.