Skip to content

workflow: functionality changes release notes addition #933

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Feb 8, 2019
Merged

workflow: functionality changes release notes addition #933

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c6c56d9
workflow: functionality changes release notes addition
0xc0170 Jan 31, 2019
0003157
workflow: fix impact analysis vs description
0xc0170 Jan 31, 2019
237b127
workflow: functionality change migration fix
0xc0170 Jan 31, 2019
efc2e0b
workflow: functionality change or addition fix
0xc0170 Feb 1, 2019
f8acd99
Edit workflow.md
Feb 1, 2019
7b86eb3
workflow: impact to effects wording fix
0xc0170 Feb 5, 2019
b85177b
Add requested note to workflow.md
Feb 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/reference/contributing/guidelines/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -94,10 +94,18 @@ 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:

- A brief description of changes introduced.
- An impact analysis: components affected, potential consequences for users and reasons for the addition or change.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@0xc0170 0xc0170 Feb 4, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- Migration guidance: actions for updating the current code. Please include code snippets to illustrate before and after the addition or change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, a note is useful

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:
Expand Down Expand Up @@ -170,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.
Expand Down