Commit fe361213 authored by Matthias Simon's avatar Matthias Simon
Browse files

Update CONTRIBUTION.md

parent 5866f3f6
Loading
Loading
Loading
Loading
+40 −25
Original line number Diff line number Diff line
# 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.