update: add descripton of issue templates in the contributing guidelines

Signed-off-by: Daniel Oliveira <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,7 +3,7 @@ name: Bug report
 about: Create a report to help us improve
 title: "[BUG] add short description of bug"
 labels: bug
-assignees: danielRep
+assignees: ''
 
 ---
 

.github/pull_request_template.md

@@ -1,41 +1,50 @@
 ## PR Description
 
-Please include a summary of the change that tries to answer the following
-questions:
-- Why is this change required?
-- What problem does it solve? What was the previous behavior/warning/error?
-- Is the bug described in any issue ticket number?
-- Which main documentation topics are affected?
+Before saving the PR, please delete this description and add only your summary/description of the PR.
+Please include a summary of the change that tries to answer the following general questions:
+- What does this change introduce? Why is it required?
+- Which main blocks are affected?
+
+If your changes are included in the following categories, please try also to answer to these specific questions to enhance your summary:
+- The PR changes introduces a new feature...
+  - What new feature is being introduced?
+  - Is the feature described in any of the requirements?
+- The PR changes solves a bug...
+  - What bug does it solve? What was the previous behavior/warning/error?
+  - Is the bug described in any issue ticket number?
+- The PR changes refactors a code/doc block...
+  - Why the code/doc block needed to be refactored?
+  - Is the improvement described in any issue ticket number?
+- The PR changes the build system...
+  - What building block of the build system was changed?
+  - Has any external dependency been introduced?
+- The PR changes adds new tests...
+  - What new tests were introduced or corrected?
 
 ### Type of change
 
-Before saving the PR, please delete this description and the below options that
-are not relevant. If you are not sure which type of change are you introducing,
-please read [Contributing](source/development/contributing.rst) documentation.
+Before saving the PR, please delete this description and the below options that are not relevant.
+If you are not sure which type of change are you introducing, please read [Contributing](https://github.com/bao-project/bao-docs/blob/main/source/development/contributing.rst) documentation.
 
-- [ ] **fix**: bug fix
-  - [ ] Fixes a specific issue: <#ticket-number>
-- [ ] **ref**: refactoring of a code/doc block
+- **feat**: introduces a new functionality
   - Logical unit: <name>
-- [ ] **feat**: introduces a new functionality
+- **fix**: bug fix
   - Logical unit: <name>
-- [ ] **build**: changes that affect the build system or external dependencies
+  - Fixes a specific issue: <#ticket-number>
+- **ref**: refactoring of a code/doc block
   - Logical unit: <name>
-- [ ] **perf**: a code change that improves performance
-- [ ] **test**: adding missing tests or correcting existing ones
-  - Test unit: <name>
-- [ ] **opt**: modifications pertaining only to optimizations
+- **build**: changes that affect the build system or external dependencies
   - Logical unit: <name>
-- [ ] **ci**: changes to the CI configuration files and scripts
+- **test**: adding missing tests or correcting existing ones
+  - Test unit/suite: <name>
+- **ci**: changes to the CI configuration files and scripts
   - CI checker unit: <name>
-- [ ] **style**: changes that do not affect the meaning of the code
-  (formatting, typos, naming, etc.)
-- [ ] **update**: changes that brings a feature, setup, or configuration up to date by adding new or updated information
+- **style**: changes that do not affect the meaning of the code (formatting, typos, naming, etc.)
+- **update**: changes that brings a feature, setup, or configuration up to date by adding new or updated information
   - Logical unit: <name>
 
 ## Checklist:
 
-- [ ] The documentation follows the style guidelines described in [here](source/development/doc_guidelines.rst).
-- [ ] I have performed a self-review of all the English grammar.
-- [ ] My changes generate no new warnings when building the documentation. If so, I have justified above.
-- [ ] I have run the CI checkers.
+- [ ] The changes follows the documentation guidelines described in [here](https://github.com/bao-project/bao-docs/blob/main/source/development/doc_guidelines.rst).
+- [ ] The changes generate no new warnings when building the project. If so, I have justified above.
+- [ ] I have run the CI checkers before submitting the PR to avoid unnecessary runs of the workflow.

source/development/contributing.rst

@@ -404,32 +404,10 @@ When submitting a PR, the title message should follow this structure:
 
 All PRs follow a designate template located in
 ``.github/pull_request_template.md`` file. Each time a contributor opens a PR,
-the github will automatically generated a body for the PR that follows that
+the Github will automatically generated a body for the PR that follows that
 template. The contributor must follow the template guidelines before submitting
 the PR.
 
-Template example (short preview):
-
-.. code-block:: markdown
-
-    # PR Description
-
-    Please include a summary of the change...
-
-    ## Type of change
-
-    Before saving the PR, please delete this description...
-
-    - [ ] **fix**: bug fix
-      - [ ] Fixes a specific issue: <#ticket-number>
-    - [ ] **ref**: refactoring of a code/doc block
-    ...
-
-    # Checklist:
-
-    - [ ] The documentation follows the style guidelines described in
-    ...
-
 .. _commit_branch_types:
 
 Commits and Branch Types
@@ -485,7 +463,11 @@ the following files set up, relative to their top-level directory:
   they can be automatically notified for code-review. The file first line
   must assign all files to the repository's **maintainers**;
 * ``.github/pull_request_template.md``: template to be automatically used and
-  generated by github when a PR is open.
+  generated by Github when a PR is open.
+* ``.github/ISSUE_TEMPLATE/bug_report.md``: template to be automatically used
+  and generated by Github when a *bug*-labeled issue is open.
+* ``.github/ISSUE_TEMPLATE/feature_request.md``: template to be automatically
+  used and generated by Github when a *feature-request*-labeled issue is open.
 
 .. _authors_and_contributors:
 
@@ -574,18 +556,47 @@ Here are a few workflows a **maintainer** should add to the repository's
 * build: build the repository for a representative set of targets and
   configurations (using GitHub Actions' strategy matrix);
 
-The **maintainers** are free to add more github workflows they feel are needed
+The **maintainers** are free to add more Github workflows they feel are needed
 due to the specificities of the repository.
 
 Repository Templates
 ********************
 
-A repository must have a template that Github's auto-populates a PR description
-field and provide a structure to what the developer must fill-in. The
-:term:`maintainer` of the repository is responsible for organizing a template
-that matches the repository specific constrains (e.g., type of changes, tests
-performed). The PR templates are described in
-``.github/pull_request_template.md``.
+The `bao-ci <https://github.com/bao-project/bao-ci>`_ repo provides a
+``.github/templates`` folder containing general templates for PRs and Issues.
+Please be advised that these only provide a set of general topics that a
+maintainer can use as a basis. The maintainer is responsible for adapting these
+templates by modifying them or adding fields that they feels are missing, given
+the repository specificities.
+
+PR Templates
+############
+
+A repository must provide a template that Github will use to auto-populate PR
+description fields, structuring the report and guiding contributors on what
+information they should provide. The :term:`maintainer` of the repository is
+responsible for setting up and organizing these templates, adapting them to the
+repository's specificities and constraints(e.g., type of changes, tests
+performed).
+
+The PR template is described in ``.github/pull_request_template.md``.
+
+Issues Templates
+################
+
+A repository must provide templates that Github will use to auto-populate issue
+description fields, structuring the report and guiding contributors on what
+information they should provide. The :term:`maintainer` of the repository is
+responsible for setting up and organizing these templates, adapting them to the
+repository's specificities and constraints.
+
+At least two issue templates must be created:
+
+* ``.github/ISSUE_TEMPLATE/bug_report.md``: consistently details and organizes
+  a bug report
+* ``.github/ISSUE_TEMPLATE/feature_request.md``: details an idea/suggestion for
+  a new feature and analyzes its trade-offs
+
 
 .. TODO: