Update the Mbed TLS README #8259

simonbutcher · 2018-09-26T15:41:36Z

Description

Update the Mbed TLS README.md file to include information contained in Mbed OS 3, which was omitted from Mbed OS 5.

Pull request type

[x] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[ ] Breaking change

Add content missing from the README.md taken from the Yotta/Mbed OS 3 Readme.

simonbutcher · 2018-09-26T15:42:48Z

This should be reviewed by @RonEld, @Patater and @mpg /or/ @gilles-peskine-arm .

features/mbedtls/README.md

gilles-peskine-arm · 2018-09-26T21:55:56Z

features/mbedtls/README.md

+
+To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults.
+
+To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself.


Tag or commit? Not a branch name to get the tip of the branch? Can't I leave it blank to get the default, and would I get the latest release [master], the latest beta [development], or some untested experimental thing [we don't have this]?

mpg

I reviewed this and don't have anything to add to existing reviews. I'm happy with the changes in general, but a few details should be fixed/improved.

Numerous changes to language, grammar, and corrections, following review.

simonbutcher · 2018-10-03T11:17:57Z

I have responded to all review feedback. Please re-review and approve.

0xc0170 · 2018-10-09T15:45:18Z

@AnotherButler Please review

AnotherButler · 2018-10-09T16:05:33Z

@MelindaWeed Could you please take this?

melwee01 · 2018-10-15T06:17:22Z

Sure, looking at it now.

melwee01

I can apply most of these changes myself.

melwee01 · 2018-10-15T06:18:36Z

features/mbedtls/README.md


-The [mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledgebase articles, blogs and a support forum for questions to the community.
+Several example programs are available that demonstrate the use of Mbed TLS with


Check these line endings so they render properly.

features/mbedtls/README.md

melwee01 · 2018-10-15T06:19:54Z

features/mbedtls/README.md

+
+For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project.
+
+The Mbed TLS configuration file would be specified in the `.json` file as follows.


features/mbedtls/README.md

melwee01 · 2018-10-15T06:21:28Z

features/mbedtls/README.md

+
+## Getting Mbed TLS from GitHub
+
+Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults.


melwee01 · 2018-10-15T06:22:23Z

features/mbedtls/README.md

+Once these steps are complete, you can make your Mbed OS build normally with the new version of Mbed TLS.
+
+
+## Differences between the standalone and Mbed OS editions


Just a general comment for myself when I get into the file: take out unnecessary articles.

melwee01 · 2018-10-15T06:23:20Z

features/mbedtls/README.md

+
+## Differences between the standalone and Mbed OS editions
+
+While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition.


You should keep those differences in mind if you consult our knowlege base, as these refer to the standalone edition.

melwee01 · 2018-10-15T06:23:53Z

features/mbedtls/README.md

+Help and Support
+----------------
+
+The [Mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledge base articles and blogs. In addition there is a [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community.


function-by-function

Additionally,

Rephrase this as 'you can' statements to grab the reader more.

melwee01 · 2018-10-15T06:24:40Z

features/mbedtls/README.md

@@ -21,5 +104,4 @@ We gratefully accept bug reports and contributions from the community. There are
 -   Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions.
 -   For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for.

-Contributions should be submitted to the [standalone mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the mbed OS imported edition of mbed TLS.
-
+Contributions should be submitted to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS.


Submit contributions to...

cmonr · 2018-10-23T00:51:44Z

@melwee01 Any updates? Were you going to copy edit the suggestions, or should @sbutcher-arm ?

melwee01 · 2018-10-23T05:45:20Z

Hmm. Since the OS repo functions differently, it's harder for me to apply changes myself. Probably easier if @sbutcher-arm does it, and asks me if he has any questions.

cmonr · 2018-10-23T23:18:20Z

Hmmm. @AnotherButler, you're able to copy edit @melwee01 suggestions, correct?

simonbutcher · 2018-10-24T13:04:39Z

Should I not make the edits myself @cmonr?

0xc0170 · 2018-10-24T13:37:46Z

Should I not make the edits myself @cmonr?

Please do

cmonr · 2018-10-24T15:28:21Z

@sbutcher-arm We're just use to seeing the docs team do copy edits on their own.

Improves the language, formatting and clarity of the Mbed TLS README.md.

simonbutcher · 2018-10-24T16:12:53Z

I've addressed some of the feedback, and responded to all remaining points.

cmonr · 2018-10-24T16:21:27Z

@melwee01 @mpg @AnotherButler @RonEld When y'all get a chance.

Changes addressed. Please re-review.

melwee01 · 2018-10-25T07:05:19Z

I'm making a few additional editorial changes myself (finally know how to do that, yay).

melwee01

I've made a number of small changes myself.

RonEld

One small comment on the default Mbed TLS version being extracted

RonEld · 2018-10-25T08:22:20Z

features/mbedtls/README.md

+
+Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import a different version of Mbed TLS into an instance of Mbed OS, there is a `Makefile` script to update the local Git repository, extract a specific version, and modify the configuration files to Mbed OS defaults.
+
+To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the Git tag or commit ID of the Mbed TLS release or version you want to use, or modify the `Makefile` itself. If `MBED_TLS_RELEASE` is unset, the HEAD of the main development branch will be extracted.


If MBED_TLS_RELEASE is unset, the HEAD of the main development branch will be extracted.

This is not accurate. If it is not given as an argument to the Makefile, then the Mbed-OS release will be extracted, as you can see here

That's not what the sentence was meant to convey. I meant something like:

If MBED_TLS_RELEASE is not set in the Makefile, the HEAD of the main development branch will be extracted.

It obviously isn't clear enough.

If MBED_TLS_RELEASE is not set in the Makefile, the HEAD of the main development branch will be extracted.

Is that what you want in place of the original sentence?

Edit file, mostly for active voice and removal of marketing language.

Comment has been addressed. Feel free to re-review!

cmonr · 2018-10-26T03:23:40Z

Note: This PR is now a part of a rollup PR (#8552).

No further work is needed here, as once that PR is merged, this PR will also be closed and marked as merged.

simonbutcher · 2018-10-26T12:28:12Z

There's an open issue of clarity on one line. @RonEld raised an issue, but it hasn't been addressed by @AnotherButler's edits.

@cmonr - To fix it, do we have to create another PR now?

melwee01 · 2018-10-26T12:57:57Z

If the rollup hasn't been merged yet, can't we just make a commit to that?

0xc0170 · 2018-10-26T13:05:49Z

If the rollup hasn't been merged yet, can't we just make a commit to that?

Let's do that. There's one problem we need to fix there anyway. @sbutcher-arm commit that can be applied or just drop a line here, @melwee01 can add it this time

Update the Mbed TLS README.md

0fd0de6

Add content missing from the README.md taken from the Yotta/Mbed OS 3 Readme.

simonbutcher mentioned this pull request Sep 26, 2018

Remove Yotta support from the documentation, tests and build scripts Mbed-TLS/mbedtls#1609

Merged

4 tasks

Patater reviewed Sep 26, 2018

View reviewed changes

features/mbedtls/README.md Outdated Show resolved Hide resolved

features/mbedtls/README.md Outdated Show resolved Hide resolved

features/mbedtls/README.md Outdated Show resolved Hide resolved

0xc0170 requested review from RonEld, Patater, mpg and gilles-peskine-arm September 26, 2018 16:55

0xc0170 added the needs: review label Sep 26, 2018

gilles-peskine-arm suggested changes Sep 26, 2018

View reviewed changes

0xc0170 added needs: work and removed needs: review labels Oct 1, 2018

mpg reviewed Oct 2, 2018

View reviewed changes

Update Mbed TLS README.md followng review

fee476e

Numerous changes to language, grammar, and corrections, following review.

simonbutcher force-pushed the readme-update branch from d960bad to fee476e Compare October 3, 2018 11:17

gilles-peskine-arm approved these changes Oct 3, 2018

View reviewed changes

Patater approved these changes Oct 3, 2018

View reviewed changes

0xc0170 requested a review from AnotherButler October 9, 2018 15:44

0xc0170 approved these changes Oct 9, 2018

View reviewed changes

AnotherButler requested a review from melwee01 October 9, 2018 16:03

melwee01 previously requested changes Oct 15, 2018

View reviewed changes

Improve Mbed TLS README.md

650d8dc

Improves the language, formatting and clarity of the Mbed TLS README.md.

cmonr added needs: review and removed needs: work labels Oct 24, 2018

editorial changes, passive to active, removing redundancy

8c2bd40

melwee01 approved these changes Oct 25, 2018

View reviewed changes

mpg approved these changes Oct 25, 2018

View reviewed changes

RonEld previously requested changes Oct 25, 2018

View reviewed changes

0xc0170 added needs: work and removed needs: review labels Oct 25, 2018

Edit README.md

8bf4981

Edit file, mostly for active voice and removal of marketing language.

AnotherButler approved these changes Oct 25, 2018

View reviewed changes

cmonr added needs: CI rollup PR release-version: 5.10.3 and removed needs: work labels Oct 25, 2018

cmonr mentioned this pull request Oct 26, 2018

Rollup PR: UK Docathon pt2 #8552

Merged

cmonr merged commit 8bf4981 into ARMmbed:master Oct 27, 2018

cmonr removed the needs: CI label Oct 27, 2018

simonbutcher deleted the readme-update branch October 27, 2018 22:11

cmonr removed the rollup PR label Oct 29, 2018


		To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults.

		To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the git tag or commit id of the Mbed TLS Release or version you want to use, or alternatively you can modify the `Makefile` itself.


		The [mbed TLS website](https://tls.mbed.org/) contains full documentation for the library, including function by function descriptions, knowledgebase articles, blogs and a support forum for questions to the community.
		Several example programs are available that demonstrate the use of Mbed TLS with


		For example, if you wanted to enable the options, `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C`, and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project.

		The Mbed TLS configuration file would be specified in the `.json` file as follows.


		## Getting Mbed TLS from GitHub

		Mbed TLS is maintained and developed in the open, independently of Mbed OS, and its source can be found on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import into an instance of Mbed OS a different version of Mbed TLS, a `Makefile` script is provided to update the local git repository, extract a specific version, and to modify the configuration files to those used for the Mbed OS defaults.

		Once these steps are complete, you can make your Mbed OS build normally with the new version of Mbed TLS.


		## Differences between the standalone and Mbed OS editions


		## Differences between the standalone and Mbed OS editions

		While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition.

Update the Mbed TLS README #8259

Update the Mbed TLS README #8259

Uh oh!

Conversation

simonbutcher commented Sep 26, 2018

Description

Pull request type

Uh oh!

simonbutcher commented Sep 26, 2018

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mpg left a comment

Choose a reason for hiding this comment

Uh oh!

simonbutcher commented Oct 3, 2018

Uh oh!

0xc0170 commented Oct 9, 2018

Uh oh!

AnotherButler commented Oct 9, 2018

Uh oh!

melwee01 commented Oct 15, 2018

Uh oh!

melwee01 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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!

cmonr commented Oct 23, 2018

Uh oh!

melwee01 commented Oct 23, 2018

Uh oh!

cmonr commented Oct 23, 2018

Uh oh!

simonbutcher commented Oct 24, 2018

Uh oh!

0xc0170 commented Oct 24, 2018

Uh oh!

cmonr commented Oct 24, 2018

Uh oh!

simonbutcher commented Oct 24, 2018

Uh oh!

cmonr commented Oct 24, 2018

Uh oh!

melwee01 commented Oct 25, 2018

Uh oh!

melwee01 left a comment

Choose a reason for hiding this comment

Uh oh!

RonEld left a comment