GitHub Issues Guidelines

GitHub Issues is the issue tracker that is being used to track all changes and implementation of new code or documentation in Apache Hop. This document serves to explain the workflow that is used and what can happen after a ticket has been created. The second purpose is to explain what you need to do to create an complete ticket, doing so helps the developers to understand the request and work on it.

  1. Creating a GitHub Issue

  2. Ticket priorities

  3. Hop GitHub Issues Workflow

  4. Hop GitHub Actions

Creating a GitHub Issue

Writing a good ticket can be a difficult task, these guidelines should help you with writing a useful ticket that is easy to comprehend by the developer that will handle the task.

These criteria are only applicable when we are talking about bugs or small changes to the code. When you have a great new idea or major change for the product please start a discussion on our dev chat channel first, for more info on this please take a look at our Code Contribution Guide.

When writing a ticket for a Feature please take into account following steps:

  1. The actor - the person using the feature

  2. The something - what the user needs the feature for

  3. The Goal - why do you need this feature

As [the actor], I want [the something] so I can [the goal].

When writing a ticker for a Bug following template is preferred:

  1. Scenario - the steps you have taken

  2. Expected result - what result were you expecting

  3. Actual result - what actually happened when following the scenario

  4. General information - version used and system information

Scenario
When using transform "x" and setting option "a"
Expected result
I expect the result of the transform to contain the result "abc"
Actual result
But I am receiving "def"
General information
I tried this using Hop version xx on ubuntu 19.10

If possible include a sample pipeline and sample data to reproduce the situation, this will greatly improve our efficiency. If you would like to include error logs, attach them using a file or pastebin and do not paste them in the description of the issue.

Priorities used within the project

Priority 0: Outage

This is reserved only for the most critical of bugs halting all development on the project.

Example Priority 0 issues:

  • the build is broken, halting all development

  • the website is down

  • a vulnerability requires a point release ASAP

Priority 1: Critical

This is considered a high priority. Most P1 bugs should block a release. P1 bugs should not be unassigned and require frequent status updates.

Example Priority 1 issues:

  • regression in integration tests

  • important component is nonfunctional

  • performance regression

Priority 2: Default

Most tickets fall into this priority. These can be planned and executed by anyone who is interested. No special urgency is associated, but if no action is taken on a P2 ticket for a long time, it indicates it is actually just P3/nice-to-have.

Example Priority 2 issues

  • typical feature request

  • bug that affects some use cases but don’t make a component nonfunctional

Priority 3: Nice-to-have

Nice-to-have improvements.

Example Priority 3 issues

  • feature request that is nice-to-have

  • ticket filed as P2 that no one finds time to work on

Priority 4

Nice-to-have improvements that are also very small and easy. Usually it is quicker to just fix them than to file a bug, but the issue can be referenced by a pull request and shows up in release notes.

Example Priority 4 issues

  • spelling errors in comments or code

  • sonar code smells

Hop GitHub Issues Workflow

The workflow that is used in the development process of Apache Hop is the following.

  • All new issues will first get the triage status, there one of the committers will check if all needed information is included in the ticket or if a duplicate ticket already exists. This process can have multiple outcomes

    • Additional information is requested

    • The ticket is out of scope or reporter fails to reply to questions then it will be closed with a comment

The committer will always add a comment to the ticket stating his reasoning, why the ticket will not be handled

  • When a release of Apache Hop has finished the committers will go over the backlog and decide which tickets will be added to the following release. These tickets are then added to the ready for development list. Each ticket in this list is linked to a release version and the goal is to add them to the following release. When this list has been created it is not final, following exceptions can occur

    • A severe or critical bug has been created, these can get fast tracked and added to a current release

    • The reporter wants to work on the issue, when the reporter wants to be contributor for the code the ticket can be added to the current release. A committer will add the contributor to the ticket, the contributor tries to create a pull request in the same time frame as the rest of the developers.

  • When a committer or contributor is working on a ticket it will be assigned to that person

  • After the development is finished and you created a pull request the ticket will be placed In Review, one of the committers will look at the code and merge it with master if it is conforming our guidelines.

  • When a ticket is done it is ready for release

Github Actions

As a project we have added some helpers to help us manage our tickets in GitHub, When using the templates to create a GitHub Issue a bot will automatically add tags to help us filter on domains and priority. You can also use the bot to self-assign or change labels on your own issues.

Following commands are available to you on Issues you have created:

.take-issue self-assign the issue to you
.close-issue Close this issue
.reopen-issue Reopen a closed issue
.add-labels label1,label2,'label 3 with spaces'
.remove-labels label1,label2,'label 3 with spaces'
.set-labels label1,label2,'label 3 with spaces' (which removes any labels not in that set)

Edit this Page Back to top