Changing templates and PR opening requirements (#638)

* Changing templates and PR opening requirements

Signed-off-by: Ricardo Zanini <[email protected]>

* Fix a few typos and spelling

Signed-off-by: Ricardo Zanini <[email protected]>

Author: ricardozanini

.github/ISSUE_TEMPLATE/bug-report.md

@@ -5,13 +5,21 @@ labels: kind/bug
 
 ---
 
-**What happened**:
+<!-- 
+Sometimes can be hard to describe a "bug" in a specification. So, before opening
+a Bug Report, please consider opening a discussion using the "Discussions" tab.
+The community will be more than happy to clarify a concern you might have.
 
-**What you expected to happen**:
+If you see a typo, spelling error, or formatting issue in our docs, please open
+a PR.
+-->
 
-**How to reproduce it**:
+**What seems off**:
+
+**What you expected to be**:
 
 **Anything else we need to know?**:
 
 **Environment**:
-- Specification version used:
+
+- Specification version used:

.github/ISSUE_TEMPLATE/enhancement.md

@@ -5,6 +5,18 @@ labels: kind/feature
 
 ---
 
+<!-- 
+Enhancements in a specification are not always easy to describe at first glance,
+requiring some discussions with other groups before reaching a conclusion.
+
+Because of this, we kindly ask you to consider opening a discussion using the
+"Discussions" tab. The community will be more than happy to discuss your
+enhancement proposal there.
+
+If you see a typo, spelling error, or formatting issue in our docs, please open
+a PR.
+-->
+
 **What would you like to be added**:
 
-**Why is this needed**:
+**Why is this needed**:

.github/ISSUE_TEMPLATE/new-extension.md

@@ -5,6 +5,13 @@ labels: kind/feature
 
 ---
 
+<!--
+We are more than thrilled to accept a new extension! 
+
+But before that, have you considered starting a discussion with other
+contributors using the "Discussions" tab?
+-->
+
 **Describe the extension you would like to be added**:
 
-**What is the main purpose of the extension**:
+**What is the main purpose of the extension**:

.github/ISSUE_TEMPLATE/question.md

@@ -1,6 +1,16 @@
+<!--
+PLEASE READ THIS BEFORE SUBMITTING A PR!
+
+Other than typos, spelling, or formatting problems in our docs, consider first opening an ISSUE or a DISCUSSION. 
+
+Enhancements or bugs in a specification are not always easy to describe at first glance, requiring some discussions with other contributors before reaching a conclusion.
+
+We kindly ask you to consider opening a discussion or an issue using the Github tab menu above. The community will be more than happy to discuss your proposals there.
+-->
+
 **Many thanks for submitting your Pull Request :heart:!**
 
-**Please specify parts this PR updates:**
+**Please specify parts of this PR update:**
 
 - [ ] Specification
 - [ ] Schema
@@ -12,8 +22,13 @@
 - [ ] TCK
 - [ ] Other
 
+**Discussion or Issue link**:
+<!-- Please consider opening a dicussion or issue for bugs or enhancements. You can ignore this field if this is a typo or spelling fix. -->
+
 **What this PR does / why we need it**:
+<!-- Brief description of your PR / Short summary of the discussion or issue -->
 
 **Special notes for reviewers**:
 
-**Additional information (if needed):**
+**Additional information:**
+<!-- Optional -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -21,7 +21,7 @@ is the most interesting or fun.
 ## Reviewers
 
 A reviewer is a core role within the project.
-They share in reviewing issues and pull requests. Their pull request approvals 
+They share in reviewing issues and pull requests. Their pull request approvals
 are needed to merge a large code change into the project.
 
 ## Adding maintainers
@@ -57,9 +57,10 @@ becomes a maintainer once the pull request is merged.
 
 ## Subprojects
 
-Serverless Workflow subprojects all culminate in officially supported and maintained releases
-of the specification. 
-All subprojects must adhere to [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)
+Serverless Workflow subprojects all culminate in officially supported and
+maintained releases of the specification.
+All subprojects must adhere to
+[CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)
 as well as this governance document.
 
 ### Adding core subprojects
@@ -127,12 +128,13 @@ of the pull request and which areas of the project it affects.
 ## I'm a maintainer. Should I make pull requests too?
 
 Yes. Nobody should ever push to master directly. All changes should be
-made through a pull request.
+made through a pull request. Please see the [Contributing](contributing.md)
+document for more information about opening pull requests.
 
 ## Conflict Resolution
 
 If you have a technical dispute that you feel has reached an impasse with a
 subset of the community, any contributor may open an issue, specifically
 calling for a resolution vote of the current core maintainers to resolve the dispute.
 The same voting quorums required (2/3) for adding and removing maintainers
-will apply to conflict resolution.
+will apply to conflict resolution.

GOVERNANCE.md

@@ -4,7 +4,7 @@
 [<img src="http://img.shields.io/badge/web-serverlessworkflow.io-red?style=social&logo=google-chrome">](https://serverlessworkflow.io/) 
 [<img src="https://img.shields.io/twitter/follow/CNCFWorkflow?style=social">](https://twitter.com/CNCFWorkflow)
 
-##  About
+## About
 
 CNCF Serverless Workflow defines a vendor-neutral, open-source, and fully community-driven
 ecosystem for defining and running DSL-based workflows that target the Serverless technology domain.</h3>
@@ -16,7 +16,7 @@ This project is composed of:
 * [Workflow runtimes](#runtimes) supporting the specification
 * Developer [tooling support](#tooling) for writing DSL-based workflows
 
-CNCF Serverless Workflow is hosted by the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/) and was approved as a 
+CNCF Serverless Workflow is hosted by the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/) and was approved as a
 Cloud Native Sandbox level project on July 14, 2020.
 
 ## Table of Contents
@@ -27,10 +27,10 @@ Cloud Native Sandbox level project on July 14, 2020.
 - [SDKs](#SDKs)
 - [Tooling](#Tooling)
 - [Community](#Community)
-    - [Communication](#Communication)
-    - [Code of Conduct](#Code-of-Conduct)
-    - [Meetings](#Meetings)
-    - [Meeting Minutes](#Meeting-Minutes)
+  - [Communication](#Communication)
+  - [Code of Conduct](#Code-of-Conduct)
+  - [Meetings](#Meetings)
+  - [Meeting Minutes](#Meeting-Minutes)
 - [Repository Structure](#Repository-Structure)
 - [Support](#Support)
 

README.md

@@ -11,21 +11,42 @@ well as the guidelines we follow for how our documents are formatted.
 
 ## Reporting an Issue
 
-To report an issue, or to suggest an idea for a change that you haven't had time
-to write-up yet, open an [issue](https://github.com/serverlessworkflow/specification/issues). It
-is best to check our existing
-[issues](https://github.com/serverlessworkflow/specification/issues) first to see if a similar
-one has already been opened and discussed.
+If you have a question, consider opening a
+[discussion](https://github.com/serverlessworkflow/specification/discussions).
+
+To report an issue or to suggest an idea for a change that you haven't had time
+to write up yet, open an
+[issue](https://github.com/serverlessworkflow/specification/issues). It is best
+to check our existing
+[issues](https://github.com/serverlessworkflow/specification/issues) first to
+see if a similar one has already been opened and discussed.
 
 ## Suggesting a Change
 
-To suggest a change to this repository, submit a
-[pull request](https://github.com/serverlessworkflow/specification/pulls) (PR) with the complete
-set of changes you'd like to see. See the
+Enhancements or bugs in a specification are not always easy to describe at first
+glance, requiring some discussions with other contributors before reaching a
+conclusion.
+
+Before opening a pull request, we kindly ask you to consider opening a
+[discussion](https://github.com/serverlessworkflow/specification/discussions)
+or an [issue](https://github.com/serverlessworkflow/specification/issues). The
+community will be more than happy to discuss your proposals there.
+
+Having the discussion or issue settled, please submit a
+[pull request](https://github.com/serverlessworkflow/specification/pulls) (PR)
+with the complete set of changes discussed with the community. See the
 [Spec Formatting Conventions](#spec-formatting-conventions) section for the
 guidelines we follow for how documents are formatted.
 
-Each PR must be signed per the following section.
+Each PR must be signed per the following section and have a link to the issue or
+discussion.
+
+### Fixing Typos, Spelling, and Formatting issues
+
+Due to the amount of text a specification can have, typos, spelling, and
+formatting issues are pretty common. In these cases, please submit a
+[pull request](https://github.com/serverlessworkflow/specification/pulls)
+directly only with the fixes that you see fit.
 
 ### Assigning and Owning work
 
@@ -45,22 +66,22 @@ Documents in this repository will adhere to the following rules:
 
 ### Markdown style
 
-Markdown files should be properly formatted before a pull request is sent out.
-In this repository we follow the
+Markdown files should be appropriately formatted before a pull request is sent out.
+In this repository, we follow the
 [markdownlint rules](https://github.com/DavidAnson/markdownlint#rules--aliases)
 with some customizations. See [markdownlint](.markdownlint.yaml) or
 [settings](.vscode/settings.json) for details.
 
-We highly encourage to use line breaks in markdown files at `80` characters
-wide. There are tools that can do it for you effectively. Please submit proposal
-to include your editor settings required to enable this behavior so the out of
-the box settings for this repository will be consistent.
+We highly encourage using line breaks in markdown files at `80` characters
+wide. Some tools can do it for you effectively. Please submit the proposal
+to include your editor settings required to enable this behavior so the
+out-of-the-box settings for this repository will be consistent.
 
 If you are using Visual Studio Code,
 you can also use the `fixAll` command of the
 [vscode markdownlint extension](https://github.com/DavidAnson/vscode-markdownlint).
 
-To otherwise check for style violations, use
+To otherwise check for style violations, use:
 
 ```bash
 # Ruby and gem are required for mdl
@@ -84,7 +105,7 @@ make install-misspell
 make misspell
 ```
 
-To quickly fix typos, use
+To quickly fix typos, use:
 
 ```bash
 make misspell-correction