On Fri, Jan 16, 2015 at 4:00 AM, Bob Cochran <[email protected]> wrote: > Signed-off-by: Bob Cochran <[email protected]>
Thanks a lot Bob, I like your review very much, only few comments inline I agree with everything else! (otavio, you are mentioned downnnnnnn thereeeeeeeeee) > --- > release-notes/source/introduction.rst | 132 > ++++++++++++++++----------------- > 1 file changed, 65 insertions(+), 67 deletions(-) > > diff --git a/release-notes/source/introduction.rst > b/release-notes/source/introduction.rst > index a2c3e90..8316996 100644 > --- a/release-notes/source/introduction.rst > +++ b/release-notes/source/introduction.rst > @@ -3,18 +3,18 @@ > ************ > Introduction > ************ > -This document has the release notes of the |project_name| |release| > -which is a community effort to improve Freescale's SoCs support in the > -OpenEmbedded and Yocto Project projects. > +This document is the release notes for the |project_name| |release|, > +which is the result of a community effort to improve Freescale's SoC > +support for OpenEmbedded and Yocto Project.Do you ha > > .. only:: draft > > .. warning:: > > - This document is still in **draft** stage and *shouldn't beDo you ha > + This document is still in **draft** form and *shouldn't beDo you ha > considered finished*. In case you wish to contribute withDo you ha > - suggestions, fixes or comments please get in touch through the > - `meta-freescale > + suggestions, fixes or comments, then please get in touch > + through the `meta-freescale > <https://lists.yoctoproject.org/listinfo/meta-freescale>`_ > mailing list. > > @@ -27,82 +27,82 @@ OpenEmbedded and Yocto Project projects. > links to this document, how to contribute, and how to download both > the source code and several pre-built images. > > -What is the |project_name| > -========================== > +What is the |project_name|? > +=========================== Do you ha I prefer, instead of add the punctuation for the question, transform the sentence in a statement: What the |project_name| is > The |project_name| is a community-driven project to provide and > -maintain Board Support Package (BSP) metadata layers for use in the > -OpenEmbedded and Yocto Project projects with Freescale's SoCs. > +maintain Board Support Package (BSP) metadata layers for use in > +OpenEmbedded and Yocto Project with Freescale's SoCs. > > -The |project_name| follows the same Yocto Project's *release schedule* and > the > -*branch naming*, since release 1.3 (denzil). > +The |project_name| follows Yocto Project's *release schedule* and > +*branch naming* (since release 1.3, denzil). > > See the `Yocto Project Release > <https://wiki.yoctoproject.org/wiki/Releases>`_ > for details on the Yocto Project. > > Motivation > ---------- > -The |project_name| started with the goal of making the use of > -OpenEmbeedded and Yocto Project projects, with Freescale's SoCs, > -easier and providing an example of how to assemble an easy-to-use > -platform to base products on. > +The |project_name| started with the goal of easing the use of > +OpenEmbeedded and Yocto Project with Freescale's SoCs > +and providing an example of how to assemble an easy-to-use > +platform as the basis for future products. >Do you ha > -The project provides: > +The Community BSP provides: Good catch, but you can use The |project_name| provides: Instead > > * common environment configuration; > - * download several layers with `repo > <https://github.com/Freescale/fsl-community-bsp-platform>`_; > - * common `place <https://lists.yoctoproject.org/listinfo/meta-freescale>`_; > - for discussion regarding Freescale SoCs (kernels, bootloaders, user space > - packages (BSP in general), bugs, how-tos, and so on. > + * multiple download layers with the use of `repo > <https://github.com/Freescale/fsl-community-bsp-platform>`_; > + * common `location > <https://lists.yoctoproject.org/listinfo/meta-freescale>`_ > + for discussing Freescale SoCs, kernels, bootloaders, user space > + packages, (BSP in general), bugs, how-tos, and so on...Do you ha in case it is a matter of choice, I really prefer to never use suspension points (...) in technical documentation. What do you think? > > What the |project_name| is not > ------------------------------ > -The |project_name| does not have a professional support team. The members of > this > -community have full-time jobs and work on the project on spare time. Most of > them > -are working with Freescale SoCs in their full-time job, it means most of > them can > -provide a professional support if requested. > +The |project_name| does not have a paid support team. The members of this > +community have full-time jobs and work on the project in their spare time. > Most of them > +are working with Freescale SoCs in their full-time job, so it means some of > them can > +provide paid support if requested. Good catch! > > -The provided source code is not supposed to have production quality. It is a > -reference BSP and platform for people to build products on top of it. > Because of that, > -expect to have an adjustment cycle for your product when you decide to use > it as > -a reference for your next product. > +The provided BSP is not intended to be a product in itself. It is a We provide much more than only BSP, that's why we used "source code". I agree "source code" is not elegant, however between "source code" and "BSP" I'd keep source code. Do you have another suggestion? > +reference platform for people to build products with. Because of this, agree > +plan to have a development and test cycle for your product if you decide to > base it on > +this Community BSP. I like the overall change, but "Community BSP" sounds me incomplete. I would say |project_name| or only project. > > -The project is a community-driven work and it is NOT an official Freescale > support channel. > +The project is community-driven work, and it is NOT an official Freescale > support channel. > > What you can expect > ------------------- > -* You can expect help when you post a question, but please, be patient. Wait > for at > - least 2 days until thinking nobody cares about your problem. Most of time > people > - do reply when they know the answer, or try to provide advice. In case you > are > - ignored, probably nobody knows the answer; > +* You can expect help when you post a question, but please be patient. Wait > for at > + least two days before thinking no one will address your issue. Most of the > time, people > + do reply when they know an answer or will at least provide some advice. If > you don't > + receive a reply, then it may be due to no one in the community having an > adequate answer. > * The stable branch is supported for six months after the release date > (following > the Yocto Project's release schedule); > -* The upstreaming takes place as fast as possible and any needed adjustment > is > +* The upstreaming takes place as quickly as possible and any needed > adjustment is > going to be made accordingly. I agree with all the changes, but I've been using a thumb rule for technical documentation = never use will. Would you mind to remove "will" and turn this to present tense? > > What the community expects from you > ----------------------------------- > The community does expect that you contribute back by: > > - * replying when you know the answer for a question in the mailing list; > + * replying when you know the answer to a question in the mailing list; > * reviewing the patches sent to mailing list; > * testing new patches that affect you directly or indirectly; > * reporting bugs you may find; > * upstreaming bug fixes; > - * upstreaming features that may be good for community. > + * upstreaming features that may be good for the community. > > Upstream > ======== > -The |project_name| provides a BSP, test images, and demos for Freescale > -reference boards and 3rd party boards based on Freescale's SoCs. Besides the > BSP, > -a Linux-based operating system has several other packages such as ssh > client/server, > -window managers, applications, and so on. These packages are not part of the > BSP, > -in other words, when using |project_name| we are also using applications, > tools > +The |project_name| provides test images and demos in addition to the base > BSP for Freescale > +reference boards and third-party boards. In addition to the BSP, > +a Linux-based operating system typically requires several other packages, > such as ssh client/server, > +window managers, applications, and so on. These packages are not part of the > BSP. > +In other words, the |project_name| is used with applications, tools > and metadata from other projects such as OpenEmbedded and Poky. > > -The |project_name| always has a stable and a development version. You may > face > -errors that are not caused by |project_name|'s layers, but by the > -OpenEmbedded's or Poky's metadata. In this case, the error must be fixed > -in the layer it belongs. > +The |project_name| always offers a stable and a development version. > +You may face errors that are not caused by |project_name|'s layers, but > +instead by OpenEmbedded's or Poky's metadata. > +In this case, the error must be fixed in its layer. > > The following image shows the upstream levels: > > @@ -114,38 +114,37 @@ Main branch names > ----------------- > > * master-next: this branch is used to keep the patches to be built by the > autobuilder > - for the very first built test. Do not expect to have a clear merging > schedule, > - or to have a stable project; > + for the very first test build. Do not expect to have a clear merging > schedule, > + or to have a stable project when working with the master-next branch; > * master: this is the branch where development takes place. Any new feature > or > bug fix must be merged here first. This is the development of the next > stable branch; > * |version|: the latest stable branch. This branch only accepts bug fixes, > and > is supported for 6 months after the release date. > > -There are other branches which are the previous stable branches. They are > kept online > -for users' convenience, and you cannot expect backports or bug fixes. > +There are other branches available, and they are the previous stable > branches. They are kept online > +for users' convenience, and you should not expect backports or bug fixes. > > Upstreaming cycle > ----------------- > -Additionally to the normal upstreaming process when working with any Yocto > Project's > -layer, we have the BSP upstreaming cycle. > +In addition to the normal Yocto project upstream process, there is also a > BSP upstream cycle. ops, "Yocto Project" instead of "Yocto project" > > -The BSP upstreaming cycle starts just after a |freescale_release_name| > +The BSP upstream cycle starts just after a |freescale_release_name| Here I need Otavio's help. Otavio, I remember we have already discussed regarding the difference of "upstreaming" and "upstream" but now I don't remember exactly what =P I would say Bob's suggestion is ok, what do you think? > is published in `git.freescale.com > <http://git.freescale.com/git/cgit.cgi/imx/fsl-arm-yocto-bsp.git/>`_. > -The patches to adapt the recipes from **meta-fsl-bsp-release** are sent for > review > -and comments to the **meta-freescale** mailing list and are merged in the > **meta-fsl-arm**, > +The patches to adapt the recipes from **meta-fsl-bsp-release** are sent out > for review > +to the **meta-freescale** mailing list and are merged in the > **meta-fsl-arm** and > **meta-fsl-demos** layers or upstreamed to Yocto Project accordingly. > > -A more detailed step-by-step is shown below: > +A more detailed step-by-step process is shown below: > > 1. New |freescale_release_name| is published; > 2. The patches are sent to **meta-freescale**; > 3. After the review process, the patches are merged in the proper layer's > *master-next* branch; > 4. Source code is built by the autobuilder; > 5. After one week in *master-next*, it is merged in *master*; > - 6. Freescale internally bases the next |freescale_release_name| in > community source code; > + 6. Freescale internally bases the next |freescale_release_name| from the > community source code; > 7. Back to step 1. > > -It means Freescale uses the |project_name| source code with its bug fixes, > improvements, > +The result is that Freescale uses the |project_name| source code with its > bug fixes, improvements, > and any new features to create the *next* |freescale_release_name|. > > Freescale uses the latest stable branch from Yocto Project to base the *next* > @@ -155,27 +154,26 @@ reworked to be merged in the current development branch. > The differences between |project_name| and |freescale_release_name| > =================================================================== > > -The goal of both projects are different. See below the main points > +The goal for each project is different. See below for the main points > of divergence. > > |freescale_release_name| > ------------------------ > The |freescale_release_name| is intended to provide a static base for > Freescale > -to test and validate the BSP modules in the Freescale evaluation boards and > it is > +to test and validate the BSP modules with Freescale evaluation boards, and > it is > developed internally by Freescale. The set of supported boards vary from > release > -to release and is listed in the |freescale_release_name|'s release notes for > the > -respective version. > -The release points to a static revision of every included layer so, after > release > -it does not receive updates and bug fixes. > +to release and is listed in the |freescale_release_name| notes for the > +specific version. The release points to a static revision of every included > +layer. Therefore, the release does not receive updates and bug fixes. > > |project_name| > -------------- > The |project_name| is a reference system that can be used as a base for > products > and is an open project that accepts contributions from the community. > -It supports a wide range of boards which goes from Freescale evaluation > boards > -(**meta-fsl-arm** layer) to 3rd party boards (**meta-fsl-arm-extra**). > +It supports a wide range of boards which range from Freescale evaluation > boards > +(**meta-fsl-arm** layer) to third-party boards (**meta-fsl-arm-extra**). > The release is a "*moving target*”, so there are updates on top of the > released > -source code, such as addition of new features and of bug fixes. > +source code, such as the addition of new features and bug fixes. > > .. tabularcolumns:: p{5cm} | p{5cm} | p{5cm} > .. table:: Comparative between |freescale_release_name| and |project_name| > -- > 1.7.9.5 > > -- > _______________________________________________ > meta-freescale mailing list > [email protected] > https://lists.yoctoproject.org/listinfo/meta-freescale -- _______________________________________________ meta-freescale mailing list [email protected] https://lists.yoctoproject.org/listinfo/meta-freescale
