workflow: functionality changes release notes addition #933

0xc0170 · 2019-01-31T11:02:07Z

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.

Ready for reviews

cc @ARMmbed/mbed-os-maintainers

We could get some examples from current funcitonal changes and how release notes should look like. I quickly found one: ARMmbed/mbed-os#9277

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.

NirSonnenschein

look promising

NirSonnenschein · 2019-01-31T11:15:11Z

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.


must contain release notes section -> must contain a release notes section
I would also propose a title for this section
so it would be:
must contain a release notes section called "Important changes"

"important changes" is a placeholder actual name still needs to be defined

fixed, adding "Release notes" section for now

NirSonnenschein · 2019-01-31T11:16:38Z

docs/reference/contributing/guidelines/workflow.md

+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 


you might want to give examples for "description of changes" and "impact analysis" as developers can interpret these in different ways.

I split them into two points

NirSonnenschein

approved, with one small note

NirSonnenschein · 2019-01-31T12:20:33Z

docs/reference/contributing/guidelines/workflow.md

+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)


small note: in migration guidance I suggest saying it needs to specify all the actions that the user needs to take (should be self explanatory, but still).

+1, I rephrased it

0xc0170 · 2019-01-31T14:22:06Z

docs/reference/contributing/guidelines/workflow.md

+- 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
+


Maybe add a note here t hat this section will be used in official release notes ? or it's clear to reader

Agreed, a note is useful

bulislaw

Should we rewrite the "Functionality change" to talk both about new functionality but also about changing functionality. The whole page should be reviewed by docs team btw.

bulislaw · 2019-01-31T14:55:02Z

docs/reference/contributing/guidelines/workflow.md

@@ -98,6 +98,13 @@ 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 functionality? @AnotherButler

fixed in efc2e0b

Should also apply for 'Breaking Changes'

bulislaw · 2019-01-31T15:01:36Z

docs/reference/contributing/guidelines/workflow.md

@@ -98,6 +98,13 @@ 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.


I'm not sure if this paragraph keeps the spirit of the previous ones. The first and second paragraph talks exclusively about adding new functionality. Your paragraph below talks more about changing existing functionality.

I rephrased it to "Every pull request changing or adding functionality" - we want to capture additions but also changes

0xc0170 · 2019-02-01T08:21:34Z

Example for ARMmbed/mbed-os#9277 (@deepikabhavnani can help me to fix wording here - will edit).

Release notes

Add MBED_TRAP_ERRORS_ENABLED to develop profile - enables to catch printf in ISR in develop profile. These errors were silent in develop profile.
This change might result in the final binary size increase.

^^ this section would be part of pull request, script can fetch it and add it to the release notes.

bulislaw · 2019-02-01T10:25:42Z

Uhm, I like the idea of less manual work, but it also means we need to be validating it during code review. It would be good to have our release notes grammatically correct and describes the change properly (with analysis of impact and migration steps when it makes sense).

0xc0170 · 2019-02-01T12:06:32Z

@AnotherButler This is very important change to be included in the process as soon as possible. Please review

deepikabhavnani · 2019-02-01T15:49:48Z

Example for ARMmbed/mbed-os#9277 (@deepikabhavnani can help me to fix wording here - will edit).

Corrected a bit, but still @AnotherButler should verify

Release notes
Added MBED_TRAP_ERRORS_ENABLED flag to develop profile - Traps on RTX errors and invalid operations in ISR context enabled in develop profile. These errors were silent in develop profile.
This change might result in the final binary size increase.

Edit file, mostly for complete sentences and parallelism.

AnotherButler · 2019-02-01T22:36:50Z

docs/reference/contributing/guidelines/workflow.md

+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.


Query: Can we use a word other than "impact" here? It's technically imprecise language. ("Impact" implies hitting something, such as impacted teeth or a meteor impact.)

OK, what other synonym could be used? I've checked some, could not find anything similar to this one.

I found usually "impact analysis" in some software journals. See for instance https://www.guru99.com/impact-analysis-software-testing.html

0xc0170 · 2019-02-05T08:45:19Z

@AnotherButler Fixed impact as proposed, I would still go with as it was. An analysis of effects works as well

adbridge · 2019-02-05T13:31:56Z

Uhm, I like the idea of less manual work, but it also means we need to be validating it during code review. It would be good to have our release notes grammatically correct and describes the change properly (with analysis of impact and migration steps when it makes sense).

For functionality changes and breaking changes where a 'Release notes' we should add docs team as reviewers just for that section.

Add requested note to clarify content will be used in the official release note.

AnotherButler · 2019-02-05T21:07:49Z

Do we know why Travis is failing?

0xc0170 · 2019-02-07T08:42:22Z

Travis having networking issues, restarted the build. It happens from time to time for other projects as well, restarting helps

0xc0170 · 2019-02-07T13:50:13Z

@AnotherButler All green, lets merge this in and let us know once it's in, we will bookmark this in the docs to share with the teams

Apply changes from PR #933 to add functionality changes and some copy edits.

NirSonnenschein reviewed Jan 31, 2019

View reviewed changes

workflow: fix impact analysis vs description

0003157

NirSonnenschein approved these changes Jan 31, 2019

View reviewed changes

workflow: functionality change migration fix

237b127

0xc0170 force-pushed the dev_functionalitychange_releasenotes branch from 4cfd9b0 to 237b127 Compare January 31, 2019 12:27

0xc0170 commented Jan 31, 2019

View reviewed changes

bulislaw reviewed Jan 31, 2019

View reviewed changes

workflow: functionality change or addition fix

efc2e0b

simonbutcher approved these changes Feb 1, 2019

View reviewed changes

SeppoTakalo approved these changes Feb 1, 2019

View reviewed changes

Patater approved these changes Feb 1, 2019

View reviewed changes

bulislaw approved these changes Feb 1, 2019

View reviewed changes

0xc0170 mentioned this pull request Feb 1, 2019

RollUp PR Crypto with ITS ARMmbed/mbed-os#9529

Merged

Edit workflow.md

f8acd99

Edit file, mostly for complete sentences and parallelism.

AnotherButler reviewed Feb 1, 2019

View reviewed changes

0xc0170 mentioned this pull request Feb 4, 2019

Merge feature cellular refactor ARMmbed/mbed-os#9568

Merged

workflow: impact to effects wording fix

7b86eb3

Add requested note to workflow.md

b85177b

Add requested note to clarify content will be used in the official release note.

AnotherButler approved these changes Feb 5, 2019

View reviewed changes

This was referenced Feb 7, 2019

Implement Linker command/response files in make export ARMmbed/mbed-os#9596

Merged

Improvement to artifact delivery method ARMmbed/mbed-os#9633

Merged

This was referenced Feb 7, 2019

Adds an NFC System Test suite ARMmbed/mbed-os#9184

Merged

LoRaWAN: Retiring LoRaWANBase class ARMmbed/mbed-os#9219

Merged

AnotherButler merged commit e754bc7 into ARMmbed:development Feb 8, 2019

AnotherButler pushed a commit that referenced this pull request Feb 8, 2019

Add functionality changes to workflow.md

f8e94e6

Apply changes from PR #933 to add functionality changes and some copy edits.

0xc0170 deleted the dev_functionalitychange_releasenotes branch February 11, 2019 09:34

		@@ -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.

		@@ -98,6 +98,13 @@ 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.

workflow: functionality changes release notes addition #933

workflow: functionality changes release notes addition #933

Uh oh!

Conversation

0xc0170 commented Jan 31, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NirSonnenschein left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NirSonnenschein left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bulislaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 Feb 1, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 commented Feb 1, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release notes

Uh oh!

bulislaw commented Feb 1, 2019

Uh oh!

0xc0170 commented Feb 1, 2019

Uh oh!

deepikabhavnani commented Feb 1, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 Feb 4, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 commented Feb 5, 2019

Uh oh!

adbridge commented Feb 5, 2019

Uh oh!

AnotherButler commented Feb 5, 2019

Uh oh!

0xc0170 commented Feb 7, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

0xc0170 commented Feb 7, 2019

Uh oh!

Uh oh!

0xc0170 commented Jan 31, 2019 •

edited

Loading

0xc0170 Feb 1, 2019 •

edited

Loading

0xc0170 commented Feb 1, 2019 •

edited

Loading

0xc0170 Feb 4, 2019 •

edited

Loading

0xc0170 commented Feb 7, 2019 •

edited

Loading