From c6c56d9486fe5d4aee0b69703c5e1c0d0a1aa3b6 Mon Sep 17 00:00:00 2001 From: Martin Kojtal Date: Thu, 31 Jan 2019 10:57:50 +0000 Subject: [PATCH 1/7] workflow: functionality changes release notes addition Every functionality change must contain release notes text addition. This will be gating functionality change integration. A user does not need to go through PRs to see what has changed, read the section: "Functionality changes" in the release notes. --- docs/reference/contributing/guidelines/workflow.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 15671912ed..49473019ff 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -98,6 +98,12 @@ Any change in the functionality, it can be adding a new feature, adding a new me 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, it's easy for a new feature to introduce bugs and a support burden. The introduction of new features should also come with documentation, majority of targets support and comprehensive test coverage proving the correctness of the feature per the documentation. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases. +Every functionality change pull request must contain release notes section addition to describe the change to users. + +It must contain: +- description of changes with impact analysis +- migration guidance: before and after (good to include code snippets to illustrate) + 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. Each feature has a tech lead. This person is responsible for: From 0003157b6946aefaa5c83e18bddca93e5227a1b6 Mon Sep 17 00:00:00 2001 From: Martin Kojtal Date: Thu, 31 Jan 2019 12:09:06 +0000 Subject: [PATCH 2/7] workflow: fix impact analysis vs description --- docs/reference/contributing/guidelines/workflow.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 49473019ff..2dbf9f8f68 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -98,10 +98,11 @@ Any change in the functionality, it can be adding a new feature, adding a new me 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, it's easy for a new feature to introduce bugs and a support burden. The introduction of new features should also come with documentation, majority of targets support and comprehensive test coverage proving the correctness of the feature per the documentation. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases. -Every functionality change pull request must contain release notes section addition to describe the change to users. +Every functionality change pull request must contain a release notes section called "Release notes" to describe the changes to users. It must contain: -- description of changes with impact analysis +- brief description of changes introduced +- impact analysis - identify components affected, what are potential consequences for users, why do we need this - migration guidance: before and after (good to include code snippets to illustrate) 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. From 237b127445df43dfc2ce3cb4289f3e9be5ca4ea1 Mon Sep 17 00:00:00 2001 From: Martin Kojtal Date: Thu, 31 Jan 2019 12:26:28 +0000 Subject: [PATCH 3/7] workflow: functionality change migration fix --- docs/reference/contributing/guidelines/workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 2dbf9f8f68..125d639ad7 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -103,7 +103,7 @@ Every functionality change pull request must contain a release notes section cal It must contain: - brief description of changes introduced - impact analysis - identify components affected, what are potential consequences for users, why do we need this -- migration guidance: before and after (good to include code snippets to illustrate) +- migration guidance: actions for updating the current code. Good to include code snippets to illustrate, before/after 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. From efc2e0b75e523a867826884494add967a68c5b73 Mon Sep 17 00:00:00 2001 From: Martin Kojtal Date: Fri, 1 Feb 2019 07:19:22 +0000 Subject: [PATCH 4/7] workflow: functionality change or addition fix --- docs/reference/contributing/guidelines/workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 125d639ad7..9ef3b115e5 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -98,7 +98,7 @@ Any change in the functionality, it can be adding a new feature, adding a new me 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, it's easy for a new feature to introduce bugs and a support burden. The introduction of new features should also come with documentation, majority of targets support and comprehensive test coverage proving the correctness of the feature per the documentation. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases. -Every functionality change pull request must contain a release notes section called "Release notes" to describe the changes to users. +Every pull request changing or adding functionality must contain a release notes section called "Release notes" to describe the changes to users. It must contain: - brief description of changes introduced From f8acd9912e221538603caecf1cf8991ba8472bb7 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Fri, 1 Feb 2019 16:35:57 -0600 Subject: [PATCH 5/7] Edit workflow.md Edit file, mostly for complete sentences and parallelism. --- .../contributing/guidelines/workflow.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 9ef3b115e5..811caa0cd9 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -82,7 +82,7 @@ Release: patch #### Refactor -A refactor is a contribution that modifies the codebase without fixing a bug or changing the existing behavior. Examples of this would be 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. +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 @@ -94,16 +94,17 @@ Release: patch #### Functionality change -Any change in the functionality, it can be adding a new feature, adding a new method or a function. Software language does not matter. +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, it's easy for a new feature to introduce bugs and a support burden. The introduction of new features should also come with documentation, majority of targets support and comprehensive test coverage proving the correctness of the feature per the documentation. Feature PRs are treated cautiously, and new features require a new minor version for the codebase. Features are candidates for feature releases. Every pull request changing or adding functionality must contain a release notes section called "Release notes" to describe the changes to users. It must contain: -- brief description of changes introduced -- impact analysis - identify components affected, what are potential consequences for users, why do we need this -- migration guidance: actions for updating the current code. Good to include code snippets to illustrate, before/after + +- A brief description of changes introduced. +- An impact analysis: components affected, potential consequences for users and reasons for the addition or change. +- Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change. 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. @@ -177,16 +178,16 @@ If a pull request is idle for more than two weeks, it will be closed. The author #### Reviews -All pull requests must be reviewed. The Arm Mbed CI bot determines the most suitable person to review the pull request (based on the files changed) and tags that person accordingly. Specific, a PR creator can request reviewers by @ tagging people or teams in the *Reviewers* section of the pull request template. For example, @personA @TeamB. +All pull requests must be reviewed. The Arm Mbed CI bot determines the most suitable person to review the pull request (based on the files changed) and tags that person accordingly. A PR creator can request specific reviewers by @ tagging people or teams in the *Reviewers* section of the pull request template. For example, @personA @TeamB. GitHub dismisses a reviewer's status after any change to the pull request commit history (such as adding a new commit or rebasing). Smaller changes, such as documentation edits or rebases on top of latest master, only require additional review by maintainers. Their approval is sufficient because a team assigned as a reviewer already approved the pull request. Label: `needs: review` Time: 3 days for reviewers to leave feedback after the maintainers add the "needs: review" label. -#### The CI (Continuous Integration) testing +#### The Continuous Integration (CI) testing -There are many [CI systems available](../contributing/workflow.html#guidelines-for-github-pull-requests) for testing Mbed OS pull requests and braches. Which CI tests we run against a particular pull request depends on the effect that pull request has on the code base. Irrespective of which CI tests run, Mbed OS has an all green policy, meaning that all the CI jobs that are triggered must pass before we merge the pull request. +There are many [CI systems available](../contributing/workflow.html#guidelines-for-github-pull-requests) for testing Mbed OS pull requests and braches. Which CI tests we run against a particular pull request depends on the effect that pull request has on the code base. Irrespective of which CI tests run, Mbed OS has an all-green policy, meaning that all the CI jobs that are triggered must pass before we merge the pull request. Label: `needs: CI` Time: 1 day for CI to complete and report back results. From 7b86eb36b149e617b2c76c29a268ac9c2b4e7cab Mon Sep 17 00:00:00 2001 From: Martin Kojtal Date: Tue, 5 Feb 2019 08:44:19 +0000 Subject: [PATCH 6/7] workflow: impact to effects wording fix --- docs/reference/contributing/guidelines/workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 811caa0cd9..3dd33bdbe6 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -103,7 +103,7 @@ Every pull request changing or adding functionality must contain a release notes It must contain: - A brief description of changes introduced. -- An impact analysis: components affected, potential consequences for users and reasons for the addition or change. +- An analysis of effects: components affected, potential consequences for users and reasons for the addition or change. - Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change. 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. From b85177bebcd879e7fd153c54152cd59c2b61e9ee Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 5 Feb 2019 08:53:50 -0600 Subject: [PATCH 7/7] Add requested note to workflow.md Add requested note to clarify content will be used in the official release note. --- docs/reference/contributing/guidelines/workflow.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/contributing/guidelines/workflow.md b/docs/reference/contributing/guidelines/workflow.md index 3dd33bdbe6..39171d81be 100644 --- a/docs/reference/contributing/guidelines/workflow.md +++ b/docs/reference/contributing/guidelines/workflow.md @@ -106,6 +106,8 @@ It must contain: - An analysis of effects: components affected, potential consequences for users and reasons for the addition or change. - Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change. +**Note:** We may use this content in our official release notes. + 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. Each feature has a tech lead. This person is responsible for: