[meta-freescale] [Documentation][PATCH] release-notes: grammar edits to introduction
Daiane Angolini
daiane.list at gmail.com
Fri Jan 16 04:24:57 PST 2015
On Fri, Jan 16, 2015 at 4:00 AM, Bob Cochran <yocto at mindchasers.com> wrote:
> Signed-off-by: Bob Cochran <yocto at mindchasers.com>
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
> meta-freescale at yoctoproject.org
> https://lists.yoctoproject.org/listinfo/meta-freescale
More information about the meta-freescale
mailing list