The use of issues
You can contribute to ASAM projects directly with issues. These issues can be created and managed in the respective remote repository of the project. We recommend using issue boards for managing issues in projects.
Make discussions accessible
It must be possible for every project member to contribute to and give feedback on the topic of discussion directly. For this purpose, all content discussions shall happen through issues. This also applies to discussion results from some subgroup meetings. The output of a discussion pertaining to any topic shall be documented in its respective issue.
Gather topics in issues
|
A clean issue contains the following things:
|
If your project is on ASAM GitLab, see the GitLab instructions for creating issues.
If your project is on GitHub, see the GitHub instructions for creating issues.
Every topic shall have its own issue.
Keep issues granular and focused
If a topic is too complex for a single issue, break it down into smaller parts. This can be either done throuh the use of linked issues or through the creation of tasks, both of which serve the purpose of capturing individual steps needed to complete or close an issue.
Linking issues
Issues can be linked to each other in order to make a relationship or dependency visible. See the GitLab documentation.
Tasks
Tasks are a way to capture steps needed to complete/close an issue, they can be separately tracked in Gitlab and make it easier to break down complex issues. See the Gitlab documentation for further details.
Use issue templates
Issues should be created using the provided issue templates in the repository.
| The issue templates are provided by ASAM and are available by default in the repository. |
Each issue template contains a description (as comments) on when to use them and what content to add where.
Label issues correctly
The use of issue labels is required for filtering and sorting issues more efficiently. Each issue and merge/pull request shall apply workflow relevant state, resolution and type labels as prescribed by the contribution workflow.
A project may also define additional labels, for example for further technical categorization of issues. If such labels are introduced, the group shall document these labels by providing an exhaustive description with the label definition.
Existing labels as defined in the contribution workflow shall not be replaced or extended. This pertains to type, state and resolution labels. See the label overview for further details.
Discuss issues
The content of issues is discussed and resolved through comments and replies to previous comments.
| Content | Comments | Replies | ||||
|---|---|---|---|---|---|---|
The issue content (body) contains the definition of the issue. In the case of a feature, it contains the proposed content/change. |
A comment to an issue is a new topic that is independent from any previous comment. A user comments on the issue to partake in the discussion of this topic.
|
A reply is a comment created as a reply to a previous comment. It creates a thread. To continue the discussion, reply on the thread.
|
Due dates
The due date in issues shall be used to indicate the expected finalization date for the development of the solution. This date marks the point at which the solution can be reviewed and, ideally, accepted for integration.
ASAM recommends that solution development for issues is scoped to require no more than 4 weeks. This means that issues where the solution is expected to be more complex should be split into multiple smaller ones, each with an expected resolution time of 4 weeks or less.
If an issue is split into multiple sub-issues or tasks, assign due dates for the issue as well as the sub-issues. In this case, the due date of the issue itself may exceed the 4 week recommendation. However, the sub-issues should then stick to that limit.
Close issues
An issue shall be closed once its discussion is resolved or the issue has been dismissed.
Possible resolutions:
-
The questions of the issue have been answered
-
The bug has been fixed and the fixes have been reviewed and merged
-
The feature has been developed, reviewed, and merged
It is best practice to close an issue immediately after one of the closing conditions has been met.
Additionally, an issue may also be closed without resolution if
-
it has become obsolete and/or will not be fixed
-
it is a duplicate (i.e. another issue deals with the same topic already)