feat/repo_templates: add PR and issues templates to bao-docs and documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG] add short description of bug"
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior :
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[FEAT-REQ] add short description of the feat-request"
+labels: feature-request
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/pull_request_template.md

@@ -0,0 +1,50 @@
+## PR Description
+
+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](https://github.com/bao-project/bao-docs/blob/main/source/development/contributing.rst) documentation.
+
+- **feat**: introduces a new functionality
+  - Logical unit: <name>
+- **fix**: bug fix
+  - Logical unit: <name>
+  - Fixes a specific issue: <#ticket-number>
+- **ref**: refactoring of a code/doc block
+  - Logical unit: <name>
+- **build**: changes that affect the build system or external dependencies
+  - Logical unit: <name>
+- **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
+  - Logical unit: <name>
+
+## Checklist:
+
+- [ ] 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

@@ -222,11 +222,14 @@ are created.
 
 .. _commit_guidelines:
 
-Commit and Pull-Request Guidelines
+Commit, Branch, and PRs Guidelines
 ----------------------------------
 
-All contributions must be submitted via Github PRs. You should ensure
-that all commits within the :term:`PR`:
+PRs: Commit History
+*******************
+
+All contributions must be submitted via Github PRs. You should ensure that all
+commits in the history within the :term:`PR`:
 
 * have messages that follow the :ref:`conventional commit style<commits_style>`
 * introduce small, self-contained logical units of modifications/extensions
@@ -252,8 +255,11 @@ that all commits within the :term:`PR`:
   commits contain a sign-off message<commit_signoff>`, acknowledging the
   :ref:`DCO<dco>`;
 
-Commits: Structure and Format
-*****************************
+Commits: Structure, Format, and Sign-off
+****************************************
+
+All commits follow a set of guidelines for the message structure and format.
+Moreover, they should all be sign-off by the contributor.
 
 .. _commits_style:
 
@@ -361,7 +367,7 @@ that comply with the following list:
 .. _commit_signoff:
 
 Commit Sign-off
-***************
+###############
 
 All commits must contain a sign-off message that attests you adhere to the
 :ref:`DCO<dco>` containing:
@@ -382,11 +388,56 @@ commit, you should add your sign-off right after the previous author. Make sure
 that your local git name and email configuration are correct and match the ones
 used in you GitHub account.
 
-.. code-block:: none
+.. code-block:: shell
 
     git config --global user.name "Your Name"
     git config --global user.email "your.email@example.com"
 
+PRs: Title and Body (Templates)
+###############################
+
+When submitting a PR, the title message should follow this structure:
+
+.. code-block:: none
+
+    <branch-type>/<branch-name>: <short-summary>
+
+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
+template. The contributor must follow the template guidelines before submitting
+the PR.
+
+.. _commit_branch_types:
+
+Commits and Branch Types
+************************
+
+The following are the allowed types for topic branches, commits, and PRs:
+
+* ``fix``: bug fix
+* ``ref``: refactoring of a code block that neither fixes a bug nor adds a
+  feature
+* ``feat``: a new feature
+* ``build``: changes that affect the build system or external dependencies
+* ``doc``: documentation only changes [#]_
+* ``perf``: a code change that improves performance
+* ``wip``: a code change that is still a work in progress
+* ``exp``: a code change that is purely experimental for now
+* ``test``: adding missing tests or correcting existing ones
+* ``opt``: modifications pertaining only to optimizations
+* ``ci``: changes to the :term:`CI` configuration files and scripts [#]_
+* ``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 (e.g., updating a version, adding a new
+  item to a list, updating CODEOWNERS, bumping the :term:`CI` repo)
+
+.. [#] Cannot be used in the `bao-docs
+    <https://github.com/bao-project/bao-docs>`_ repo.
+.. [#] Cannot be used in the `bao-ci <https://github.com/bao-project/bao-ci>`_
+    repo.
+
 
 Github Repository Setup and Management
 --------------------------------------
@@ -411,6 +462,12 @@ the following files set up, relative to their top-level directory:
 * ``.github/CODEOWNERS``: identifies the coder owners of the repository so
   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.
+* ``.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:
 
@@ -499,36 +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.
 
-.. _commit_branch_types:
+Repository Templates
+********************
 
-Commit and Branch Types
------------------------
+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.
 
-The following are the allowed types for topic branches and commits:
+PR Templates
+############
 
-* ``fix``: bug fix
-* ``ref``: refactoring of a code block that neither fixes a bug nor adds a
-  feature
-* ``feat``: a new feature
-* ``build``: changes that affect the build system or external dependencies
-* ``doc``: documentation only changes [#]_
-* ``perf``: a code change that improves performance
-* ``wip``: a code change that is still a work in progress
-* ``exp``: a code change that is purely experimental for now
-* ``test``: adding missing tests or correcting existing ones
-* ``opt``: modifications pertaining only to optimizations
-* ``ci``: changes to the :term:`CI` configuration files and scripts [#]_
-* ``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 (e.g., updating a version, adding a new
-  item to a list, updating CODEOWNERS, bumping the :term:`CI` repo)
+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
 
-.. [#] Cannot be used in the `bao-docs <https://github.com/bao-project/bao-docs>`_ repo.
-.. [#] Cannot be used in the `bao-ci <https://github.com/bao-project/bao-ci>`_  repo.
 
 .. TODO: