From fe361213ec20635050112921da30271926c6870a Mon Sep 17 00:00:00 2001 From: Matthias Simon Date: Wed, 18 Sep 2024 12:32:31 +0200 Subject: [PATCH] Update CONTRIBUTION.md --- CONTRIBUTING.md | 65 ++++++++++++++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89311db..d89e528 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,34 @@ +# Contribution Guide + +This guide describes how to create change requests. It further describes the +process for handling requests and also some basic guidelines for making +changes. + +You do not need to be an ETSI member to create a change request. + ## Creating a Change Request -[Create a brief issue](https://labs.etsi.org/rep/mts/ttcn3/standard/-/issues/new) -describing desired change request and choose a template that fits your request -best: +The first step for changing the standard, is to [create a brief +issue](https://labs.etsi.org/rep/mts/ttcn3/standard/-/issues/new) describing +desired change. Choose a template that fits your request best. The templates +will help you to provide the necessary information and to structure your +request. ![issue templates](assets/issue-templates.png) +Following templates are available: + The **Editorial Changes** template is used for changes that do not affect meaning of the standard. For example, fixing typos, grammar, or formatting. -Create a **Bug Report** if the standard does not specify TTCN-3 as intended. For -example, if two specifications contradict each other, or if an example does not -reflect defined behavior. - **Clarification Needed** is used when the standard is unclear or ambiguous. For example, if a term is not defined, or if an enumeration is missing a value and it is unclear if this is on purpose. +Create a **Bug Report** if the standard does not specify TTCN-3 as intended. For +example, if two specifications contradict each other, or if an example does not +reflect defined behavior. + A **Feature proposal** is used to suggest new features, interfaces, documents or changes to existing ones. You do not need to provide a full specification document, yet. It is practice @@ -24,9 +36,12 @@ to discuss the proposal first and create the document when the proposal is accepted and all details are clear. -## The Process +## How change requests are processed + +The way how change requests are processed if very similar of it was in previous +Mantis Issue Tracker. The main difference is the different user interfaces. -### Overview +### Design Considerations GitLab is a powerful tool that can be used in many ways, it is easy to get lost in finding the perfect process. Therefore we deliberately keep it to a bare @@ -74,24 +89,24 @@ An Issue moves through the following stages: Issues that are reviewed and do not need further refinement are moved to the "Done" column -Before you close an issue, make - - -**By Design** - -This issue was examined and we decicded it wasn't a problem after all. - -**Duplicate** - -This issue already exists. - -**Fixed** -This issue was fixed. +When you close an issue, it is good practice to assign a resolve-label and a +short rationale, if possible. This serves as helpful documentation for future +reference. Following labels are available: -**Won't Fix** +* **Fixed**: The issue was implemented as suggested. Most change requests will + have this label. Additional comments are usually not required. +* **Duplicate**: If an issue is a duplicate of another request use this label. + Also reference the original issue. This makes it easier to navigate changes. +* Use the **Won't Fix** label for requests that were rejected. If possible add + a short rationale why the request was rejected, or reference a decision + record. Such documentation becomes valuable, should a request re-opened. For + example as is was with the shorthand assignments (`i++`). +* The label **By Design** is used to clarify that the standard is correct and + the issue is not a bug. For example, someone could create a bug-report that + inout-parameters should not require strong-typing, but this is by design. It + avoid issues with references to unions. -This issue examined and we decided to live with it. ## Guidelines for Writing @@ -107,7 +122,7 @@ This issue examined and we decided to live with it. * A section should contain either subsections or text, but never both. * Keep examples small, simple, and narrowly focused without using unnecessary features. -* Avoid using quoted text, as in "natural type". If it is a term, except for +* Avoid using quoted text, as in "base type". If it is a term, except for its first use, it should be in regular font without the quotes and defined in the Terms-and-definitions clause. If it is not a term use the right term or other English text. -- GitLab