Update the workflow sections

This commit updates the pull request sections to detail the new
pull request template.

Author: adbridge

docs/reference/contributing/guidelines/workflow.md

@@ -61,90 +61,142 @@ If commits do not follow the above guidelines, we may request that you modify th
 
 [How We Release Arm Mbed OS](../introduction/how-we-release-arm-mbed-os.html) explains Mbed OS versioning.
 
-## Pull request types
+## Pull request template
 
-We consider the following pull request types.
+The following template is automatically provided on the raising of a pull request against mbed-os.
+The details required will depend on the type of pull request being raised. See below for a more detailed
+explanation of the requirements.
 
-### Fix
+    ### Description (*required*)
 
-A bug fix is a change that fixes a specific defect in the codebase with backward compatibility. These are the highest priority because of the positive effect the change will have on users developing against the same code. A bug fix should be limited to restoring the documented or proven otherwise, originally intended behavior. Every bug fix should contain a test to verify results before and after the pull request. Bug fixes are candidates for patch releases. Large, nontrivial bug fixes approaching the size of refactors run the risk of being considered refactors themselves.
+    ##### Summary of change (*What the change is for and why*)
 
-Release: patch
 
-### Refactor
+    ##### Documentation (*Details of any document updates required*)
 
-A refactor is a contribution that modifies the codebase without fixing a bug or changing the existing behavior. Examples of this are moving functions or variables between translation units, renaming source files or folders, scope modification for nonpublic code, documentation structure changes and test organization changes. There is always the risk that someone depended on the location or name before a refactor; therefore, these are lower in priority than bug fixes and might require detailed justification for the change. Refactors are candidates for feature releases.
 
-Release: feature
+    ----------------------------------------------------------------------------------------------------------------
+    ### Pull request type (*required*)
 
-### Target update
+        [] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
+        [] Feature update (New feature / Functionality change / New API)
+        [] Major update (Breaking change E.g. Return code change / API behaviour change)
 
-Updating target implementation (adding a new target or updating already supported target) is a change for a patch release.
+    ----------------------------------------------------------------------------------------------------------------
+    ### Test results (*required*)
 
-A test report for the new target must be part of the pull request. The new target must pass all Mbed OS functional and system validation tests (using `mbed test` command) for the current Mbed OS major release, including all Mbed OS supported toolchains.
+        [] No Tests required for this change (E.g docs only update)
+        [] Covered by existing mbed-os tests (Greentea or Unittest)
+        [] Tests / results supplied as part of this PR
+        
+        
+    ----------------------------------------------------------------------------------------------------------------
+    ### Reviewers (*optional*)
 
-Release: patch
 
-### Functionality change
+    ----------------------------------------------------------------------------------------------------------------
+    ### Release Notes (*required for feature/major PRs*)
 
-A functionality change can be any change in the functionality, including adding a new feature, a new method or a function. Software language does not matter.
 
-A feature contribution contains a new API, capability or behavior. It does not break backward compatibility with existing APIs, capabilities or behaviors. New feature contributions are very welcome in Mbed OS. However, because they add capability to the codebase, a new feature may introduce bugs and a support burden. New features should also come with documentation, support for most targets and comprehensive test coverage. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases.
+    ##### Summary of changes
 
-Every pull request changing or adding functionality must contain a "Release notes" section describing the changes to users.
+    ##### Impact of changes
 
-It must contain:
+    ##### Migration actions required
 
-- A brief description of changes introduced, including justification.
-- An analysis of effects: components affected and potential consequences for users.
-- Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change.
 
-<span class="notes">**Note:** We may use this content in our official release notes.</span>
+### Description field
 
-For more details, please see the [pull request template addition for functional changes](#pull-request-template-functional-changes).
+There are two parts to the description, both of which are required.
+The first is a summary of the pull request. This should clearly state the reason for the PR and what 
+the changes entail. The second part requires the author to state what, if any, documentation changes 
+also need to be made to accompany the changes.
 
-We initially implement new features on separate branches in the Mbed OS repository. Mbed OS maintainers create the new branches by following the naming convention: "feature-" prefix.
+### Pull request type
 
-Each feature has a tech lead. This person is responsible for:
+There are three pull request types and these correspond to the 3 main categories specified in semantic versionning, Patch, Feature (Minor) and Major.
 
-- Rebasing often to track master development.
-- Reviewing any addition to the feature branch (approval required by the feature tech lead or another assigned person).
+#### Patch update
 
-Release: feature
+This can contain any of the following changes:
 
-### Documentation update
+##### Bug Fix
 
-Documentation updates include changes to markdown files or Doxygen documentation (comment-only changes).
+A bug fix is a change that fixes a specific defect in the codebase with backward compatibility. These are the highest priority because of the positive effect the change will have on users developing against the same code. A bug fix should be limited to restoring the documented or proven otherwise, originally intended behavior. Every bug fix should contain a test to verify results before and after the pull request. Bug fixes are candidates for patch releases. Large, nontrivial bug fixes approaching the size of refactors run the risk of being considered refactors themselves.
+
+##### Refactor
+
+A refactor is a contribution that modifies the codebase without fixing a bug or changing the existing behavior. Examples of this are moving functions or variables between translation units, renaming source files or folders, scope modification for nonpublic code, documentation structure changes and test organization changes. There is always the risk that someone depended on the location or name before a refactor; therefore, these are lower in priority than bug fixes and might require detailed justification for the change. Refactors are candidates for feature releases.
+
+##### Target update
+
+Updating target implementation (adding a new target or updating already supported target) is a change for a patch release.
+
+A test report for the new target must be part of the pull request. The new target must pass all Mbed OS functional and system validation tests (using `mbed test` command) for the current Mbed OS major release, including all Mbed OS supported toolchains.
+
+##### Documentation update
 
-Release: patch
+Documentation updates include changes to markdown files or Doxygen documentation (comment-only changes).
 
-### Test update
+##### Test update
 
 Test updates include updates to a new test unit or test case.
 
-Release: patch
+#### Feature update
+
+This can be any change in the functionality, including adding a new feature, a new method or a function. Software language does not matter.
+
+A feature contribution contains a new API, capability or behavior. It does not break backward compatibility with existing APIs, capabilities or behaviors. New feature contributions are very welcome in Mbed OS. However, because they add capability to the codebase, a new feature may introduce bugs and a support burden. New features should also come with documentation, support for most targets and comprehensive test coverage. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases.
+
+We initially implement new features on separate branches in the Mbed OS repository. Mbed OS maintainers or 
+tech leads may create the new branches by following the naming convention: "feature-" prefix.
+Each 
+Each feature has a tech lead. This person is responsible for:
 
-### Breaking change
+- Rebasing often to track master development.
+- Reviewing any addition to the feature branch (approval required by the feature tech lead or another assigned person).
 
-A breaking change is any change that results in breaking user space. It should have strong justification for us to consider it. Often, such changes can be backward compatible, for example, deprecating the old functionality and introducing the new replacement.
+#### Major update
+
+This is for breaking changes and should be rare. A breaking change is any change that results in breaking user space. It should have strong justification for us to consider it. Often, such changes can be backward compatible, for example, deprecating the old functionality and introducing the new replacement.
 
 A contribution containing a breaking change is the most difficult PR to get merged. Any breaking changes in a codebase can have a large negative impact on any users of the codebase. Breaking changes are always limited to a major version release.
 
-Every pull request with breaking change must contain a release notes section called "Release notes" to describe the changes to users.
+A project technical lead and the Mbed OS technical lead must approve breaking change pull requests.
 
-It must contain:
 
-- A brief description of changes introduced, including justification description.
-- An analysis of effects: components affected, potential consequences for users.
-- Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change.
+### Test results
 
-<span class="notes">**Note:** We may use this content in our official release notes.</span>
+This section is to indicate what test results if any are required for the PR.
+The three options are :
+* No Tests required for this change (E.g docs only update)
+* Changes will be tested by existing mbed-os tests (Greentea or Unittest)
+* Tests / results will supplied as part of this PR. For this option the test results and/or tests
+  should be posted in this section below the tick boxes.
+    
+### Reviewers
 
-Please see the [Pull request template](../contributing/workflow.html#pull-request-template-breaking-changes).
+Reviewers are automatically added by a bot based on the files that are actually changed, however this section
+gives the author the option to specify additional, specific reviewers. Required reviewers should be tagged here. E.g. @adbridge, @0xc0170
 
-A project technical lead and the Mbed OS technical lead must approve breaking change pull requests.
 
-Release: major
+### Release Notes
+
+Every pull request changing or adding functionality must fill in the "Release notes" section. Consequently
+this applies to feature and major PRs. For both these types the 'Summary of changes' section must be 
+completed. This should provide a brief description of changes introduced, including justification.
+
+For major PRs is is also compulsory to complete the 'Impact of changes' and 'Migration actions required'.
+
+The impact of changes must contain an analysis of effects: components affected and potential consequences for users.
+
+The migration actions required should describe how to migrate from a previous version of the code being
+changed to the new version. Please include code snippets to illustrate before and after the addition or 
+change.
+
+The release notes section is automatically pulled into the overall release notes for a feature or major 
+release and this should be considered when writing the entries.
+
 
 ## GitHub pull requests workflow
 
@@ -196,7 +248,14 @@ When we merge a pull request that we will publish in a patch release, we tag it
 
 The release tag has the following format:
 
-*release-version: 5.f.p* - Where `f` is the feature release and `p` the patch release.
+*release-version: m.f.p*  Where:
+
+* `m` is the major release 
+* `f` is the feature release 
+* `p` is the patch release.
+
+From time to time there may be additional suffixes added which could represent a release candidate or 
+alpha/beta release etc
 
 ## Additional labels