From 1afc1abbeed9d8c586e13ae0320f6e147a66a449 Mon Sep 17 00:00:00 2001 From: Matthias Simon <matthias.simon@nokia.com> Date: Wed, 11 Dec 2024 15:11:17 +0100 Subject: [PATCH] Update various documents --- CONTRIBUTING.md | 129 ++++++------------------------------------------ README.md | 20 +++++--- docs/README.md | 9 ++++ 3 files changed, 36 insertions(+), 122 deletions(-) create mode 100644 docs/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d89e528..efc8540 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,113 +1,12 @@ # 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 - -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. - - - -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. - -**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 -to discuss the proposal first and create the document when the proposal is -accepted and all details are clear. - - -## 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. - -### 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 -minimum initially, and improve it later based on our experience and needs. - - - - -Everything sits in a single repository. Our GitLab project has a few major -sections, reachable via sidebar. Our main focus is on **Issuess**. The other -sections **Repository**, **Merge Requests**, **CI/CD**, **Deployments** are -related to version control and open source development processes, which we do -not use at the moment. - - -### Working on Change Requests - - -* der process ist wie bei mantis, aber andere oberfläche und andere begriffe -* Der state funktioniert via label (tags) - - - -* kanban board -* columns -* label based - - -* issues are added and moved through the columns/stages - -An Issue moves through the following stages: - -### 1. Create Issue - - -### 2. To-Do - -### 3. Work In Progress - -### 4. Ready for Review - -### 5. Done - -### 6. Closed - -Issues that are reviewed and do not need further refinement are moved to the "Done" column - - -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: - -* **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. +You want to request a change to the standard or contribute to it? Great! +[This document](docs/how-to-make-a-change-request.md) should have you +covered. +There are other ways to contribute, too. Engage in discussions, report issues, ... +Also, checkout out our [standard opering procedures](docs/) for more information. ## Guidelines for Writing @@ -117,17 +16,19 @@ reference. Following labels are available: use *shall*, use *must* instead. * Use singular instead of plural. * Don't say the same thing normatively in more than on place; say it once and - point to that place, as needed. + point to that place, as needed. + Also, be careful with the use of overview tables, they can introduce + conflicts with written passages. * Normative text must be clear without examples and notes. * 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 "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. +* 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. * Technical terms should be defined in the Terms-and-definitions clause. -* Avoid enumerations where a term exists. For example, don't say - - +* Avoid enumerations where a technical term exists. For example, don't say "... + is allowed for charstring, hexstring, octetstring, bitstring and record of", + instead say "... is allowed for list-types". diff --git a/README.md b/README.md index ef50f17..ec65b26 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,18 @@ # TTCN-3 Standard This is the working space for [ETSI TC MTS TTF T040 and -previous](https://portal.etsi.org/xtfs/#/xTF/T040/). -It does _not_ contain the actual TTCN-3 standard deliverables. If you are -looking for the TTCN-3 standard, please visit the [ETSI -website](https://www.ttcn-3.org/) or its [download -section](https://www.ttcn-3.org/index.php/downloads/standards) +following](https://portal.etsi.org/xtfs/#/xTF/T040/). It does _not_ contain the +actual TTCN-3 standard deliverables. If you are looking for the finalized +TTCN-3 standard documents, please visit the [TTCN-3 website](https://www.ttcn-3.org/) or its [download section](https://www.ttcn-3.org/index.php/downloads/standards) + ## Change Request -You can request changes by creating an issue or merge request. Have a look at -the [contribution guidelines](CONTRIBUTING.md#creating-a-change-request) for -more information. +You may [request changes](https://labs.etsi.org/rep/mts/ttcn3/standard/-/issues) to the TTCN-3 standard by creating an issue or merge +request. Have a look at the standard operation procedure for [making a change +request](docs/how-to-make-a-change-request.md). + + +## Standard Procedures + +We created some [standard procedure documents](docs/) to ease getting started with our work. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5599dce --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Standard Operation Procedures + +This folder contains our standard operation procedures. Their purpose is ease +on-boardings and to provide a written reference for our team members. + +SOPs are suposed to be living documents, so if you see something that is not up +to date, please let us know or even better, submit a pull request with the +changes. +The same goes for any SOP that you think is missing. -- GitLab