Re: [ptxdist] [PATCH 2/4] doc: contributing: fix typos, add links, and make text easier to parse

[Roland Hieber <r.hieber@pengutronix.de>]

On Fri, Oct 05, 2018 at 11:45:16AM +0200, Roland Hieber wrote:
> Signed-off-by: Roland Hieber <r.hieber@pengutronix.de>
> ---
>  doc/contributing.rst | 31 ++++++++++++++++---------------
>  1 file changed, 16 insertions(+), 15 deletions(-)
> 
> diff --git a/doc/contributing.rst b/doc/contributing.rst
> index 8e2d7883d..1db596c0e 100644
> --- a/doc/contributing.rst
> +++ b/doc/contributing.rst
> @@ -6,13 +6,13 @@ PTXdist Packages
>  
>  While contributions to all parts of PTXdist are welcome, most contributions
>  concern individual packages. Here is a checklist of things to look out for
> -while creating or updating packages. These are not hard requirements but
> +while creating or updating packages. These are not hard requirements, but
>  there should be good reasons for different choices.
>  
>  How to Contribute
>  ~~~~~~~~~~~~~~~~~
>  
> -Contributions should be sent as patches to the PTXdist mailing list. This
> +Contributions should be sent as patches to the :ref:`PTXdist mailing list`. This

Oh, that section is not present until it is added in PATCH 3/4. If you
could switch those two on applying, that would be great, otherwise I'll
fix in v2.

 - Roland

>  is usually done with ``git send-email``.
>  
>  All patches must contain a descriptive subject and should, for all
> @@ -26,11 +26,11 @@ Package Builds should be Reproducible
>  
>  Many packages autodetect which features are available. As a result, the
>  exact features of a package may depend on the build host and the build
> -order of the packages. To avoid this autodetection must be restricted as
> +order of the packages. To avoid this, autodetection must be restricted as
>  much as possible.
>  
>  For **autoconf** based packages, the first step is to specify all relevant
> -``configure`` options. The :ref:`configure_helper` scripts can help filter
> +``configure`` options. The :ref:`configure_helper` script can help filter
>  out the unimportant options.
>  
>  There are also cache variables that can be used to enforce the outcome of
> @@ -55,17 +55,17 @@ Packages Suboptions
>  
>  Suboptions for PTXdist packages are useful to make parts of the package
>  optional. However, it is not always easy to decide what should be optional
> -and how to map the build system options to packages suboptions. Here are a
> +and how to map the build system options to package suboptions. Here are a
>  few guidelines to help with that.
>  
>  -  Avoid unnecessary suboptions. When in doubt, use the package default or
>     what other distributions use. If the creator of the package does not
> -   know what to choose then the user wont either.
> +   know what to choose, then the user won't either.
>  -  Use suboptions to save disk space. If a feature adds extra dependencies
> -   or uses a lot of space then a suboptions is useful to save the disk
> +   or uses a lot of space then a suboption is useful to save disk
>     space when the feature is not needed.
>  -  Try to create high-level options. Some packages have very low-level
> -   build options with very few useful combinations. Try to define
> +   build options with very few useful combinations. Try to distill the
>     high-level features or use-cases and define options for those.
>  -  Options for new use-cases can always be added later. It's perfectly
>     acceptable to just disable some unused features when creating a new
> @@ -78,19 +78,20 @@ The most common contribution to PTXdist are new versions for existing
>  packages. This is usually quite simple, but there are a few things to keep
>  in mind:
>  
> --  New versions can have new build system options that should be used.
> +-  New versions can have new build system options that should be set for
> +   reproducible builds.
>     :ref:`configure_helper` can be used to find the new options.
> --  There may be patches for the old version. Make sure they are update as
> -   well or removed if they are no longer needed.
> +-  There may be patches for the old version. Make sure they are updated as
> +   well, or removed if they are no longer needed.
>  
>  Misc
>  ~~~~
>  
> -For new Packages, the top-level option and any non-obvious suboption should
> +For new packages, the top-level option and any non-obvious suboptions should
>  have a help text. The homepage of a package or the package description from
> -other distributions a usually a good inspiration.
> +other distributions are usually a good inspiration.
>  
> -The package templates to create new packages contain commented out default
> +For new packages, the generated templates contain commented-out default
>  sections. These are meant as a helper to simplify creating custom stages.
>  Any remaining default stages must be removed.
>  
> @@ -119,7 +120,7 @@ needed. This tool contains a blacklist to filter out these options.
>  ``-h, --help``
>      Show the help message and exit
>  
> -``-p <pgk>, --pkg <pgk>``
> +``-p <pkg>, --pkg <pkg>``
>      The ptxdist package to check
>  
>  ``-o <old>, --old-src <old>``
> -- 
> 2.19.0
> 
> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de

-- 
Roland Hieber                     | r.hieber@pengutronix.de     |
Pengutronix e.K.                  | https://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de