Signed-off-by: Roland Hieber <[email protected]>
---
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
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
[email protected]
