git: b31ed853b3 - main - Remove the use of "you" in the porters handbook
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 26 Sep 2025 10:32:53 UTC
The branch main has been updated by bcr:
URL: https://cgit.FreeBSD.org/doc/commit/?id=b31ed853b37424476302c2dd45c9931ca1d055d4
commit b31ed853b37424476302c2dd45c9931ca1d055d4
Author: Benedict Reuschling <bcr@FreeBSD.org>
AuthorDate: 2025-08-29 14:04:01 +0000
Commit: Benedict Reuschling <bcr@FreeBSD.org>
CommitDate: 2025-09-26 10:32:13 +0000
Remove the use of "you" in the porters handbook
Rewrite sentences that contain 'you', which should be avoided according
to the FDP Primer. The resulting sentences are easier to understand and
often shorter. I did not change programlistings and other output as
these are from programs, which need to be changed first (out of scope of
this change).
Event: Oslo Hackathon 2025
Differential Revision: https://reviews.freebsd.org/D52238
---
.../en/books/porters-handbook/makefiles/_index.adoc | 12 ++++++++----
.../en/books/porters-handbook/upgrading/_index.adoc | 18 +++++++++---------
.../content/en/books/porters-handbook/uses/_index.adoc | 4 ++--
3 files changed, 19 insertions(+), 15 deletions(-)
diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index e98d2ff336..bf37987160 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -1073,7 +1073,11 @@ In addition, proposed category changes just naturally seem to attract controvers
Here is the procedure:
[.procedure]
-. Propose the new category on {freebsd-ports}. Include a detailed rationale for the new category, including why the existing categories are not sufficient, and the list of existing ports proposed to move. (If there are new ports pending in Bugzilla that would fit this category, list them too.) If you are the maintainer and/or submitter, respectively, mention that as it may help the case.
+. Propose the new category on {freebsd-ports}. Include a detailed rationale
+ for the new category, including why the existing categories are not
+ sufficient, and the list of existing ports proposed to move. (If there are
+ new ports pending in Bugzilla that would fit this category, list them
+ too.) Indicating that the updater is also the maintainer or submitter may be helpful to the case.
. Participate in the discussion.
. If it seems that there is support for the idea, file a PR which includes both the rationale and the list of existing ports that need to be moved. Ideally, this PR would also include these patches:
@@ -1121,7 +1125,7 @@ If `DISTVERSION` does not derive a correct `PORTVERSION`, do not use `DISTVERSIO
====
If the upstream version scheme can be derived into a ports-compatible version scheme, set some variable to the upstream version, _do not_ use `DISTVERSION` as the variable name.
-Set `PORTVERSION` to the computed version based on the variable you created, and set `DISTNAME` accordingly.
+Set `PORTVERSION` to the computed version based on the created variable and set `DISTNAME` accordingly.
If the upstream version scheme cannot easily be coerced into a ports-compatible value, set `PORTVERSION` to a sensible value, and set `DISTNAME` with `PORTNAME` with the verbatim upstream version.
@@ -2202,7 +2206,7 @@ This is a very interesting feature which can decrease that endless search for th
Just picture 2 files in `DISTFILES` and 20 sites in `MASTER_SITES`, the sites slow as hell where [.filename]#beta# is carried by all sites in `MASTER_SITES`, and [.filename]#alpha# can only be found in the 20th site.
It would be such a waste to check all of them if the maintainer knew this beforehand, would it not? Not a good start for that lovely weekend!
-Now that you have the idea, just imagine more `DISTFILES` and more `MASTER_SITES`.
+Once the concept is clear, just imagine more `DISTFILES` and more `MASTER_SITES`.
Surely our "distfiles survey meister" would appreciate the relief to network strain that this would bring.
In the next sections, information will follow on the FreeBSD implementation of this idea.
@@ -2527,7 +2531,7 @@ This does not affect `MASTER_SITES` defined in the [.filename]#Makefile#.
[[makefile-maintainer]]
== `MAINTAINER`
-Set your mail-address here. Please. _:-)_
+Set the mail-address here. Please. _:-)_
Only a single address without the comment part is allowed as a `MAINTAINER` value.
The format used is `user@hostname.domain`.
diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
index e61a88dbaf..3da3d330c5 100644
--- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
@@ -64,7 +64,7 @@ If there is no pending PR, the next step is to send an email to the port's maint
That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version), and there is no need to duplicate their work.
Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, which is just the general ports mailing list, so sending mail there probably will not help in this case.
-If the maintainer asks you to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the man:diff[1] command in the base system.
+If the maintainer requests to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the man:diff[1] command in the base system.
To create a suitable `diff` for a single patch, copy the file that needs patching to [.filename]#something.orig#, save the changes to [.filename]#something# and then create the patch:
@@ -88,7 +88,7 @@ To simplify common operations with patch files, use `make makepatch` as describe
Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#.
Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#.
-If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer.
+If the port is unmaintained, and it is actively being used, please consider volunteering to become its maintainer.
FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed.
(For a detailed description of the responsibilities of maintainers, refer to the section in the extref:{developers-handbook}[Developer's Handbook, POLICIES-MAINTAINER].)
@@ -125,8 +125,8 @@ They are easier to handle than diffs between "new and old" directories.
It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began,
or if the committer asks for something to be fixed.
Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer.
-Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages.
-These will be recorded in the log of the repository and this is the recommended way to submit your changes.
+Finally, the git patch generated by man:git-format-patch[1] includes the author information and commit messages.
+These will be recorded in the log of the repository and this is the recommended way to submit the changes.
[source,shell]
....
@@ -154,7 +154,7 @@ Also, update the checksum reference in distinfo with `make makesum`.
Before making the patch, fetch the latest repository and rebase the changes on top of it.
Watch and follow the output carefully.
-If any of the files failed to rebase, it means that the upstream files changed while you were editing the same file, and the conflicts need to be resolved manually.
+If any of the files failed to rebase, it means that the upstream files changed while local changes happened in the same file, and the conflicts need to be resolved manually.
[source,shell]
....
@@ -182,7 +182,7 @@ To generate a patch with man:git-format-patch[1]:
This will generate a patch named like `0001-foo.patch`.
This is the preferred way as it would include author identity,
-and it is also easier when you are making a series of changes that
+and it is also easier when making a series of changes that
are not meant to be squashed together.
Alternatively, to generate an unified diff with man:git-diff[1]:
@@ -193,13 +193,13 @@ Alternatively, to generate an unified diff with man:git-diff[1]:
This will generate a diff named like `foo-1.2.3.diff`.
Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message.
-After patch has been created, you can switch to the main branch for starting other developments.
+After patch has been created, switch to the main branch for starting other developments.
[source,shell]
....
% git checkout main
....
-Once the patch is accepted and merged, you can delete the local development branch if you want:
+Once the patch is accepted and merged, delete the local development branch if desired:
[source,shell]
....
% git branch -D my_branch
@@ -227,7 +227,7 @@ The format of an entry in this file is:
....
YYYYMMDD:
AFFECTS: users of portcategory/portname
- AUTHOR: Your name <Your email address>
+ AUTHOR: the name <the email address>
Special instructions
....
diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index fbdb346372..84c6123b80 100644
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -1331,7 +1331,7 @@ The framework provides the following variables to be set by the port:
`JAVA_VERSION`::
List of space-separated suitable java versions for the port. An optional `\+`
-allows you to specify a range of versions. (allowed values `8[+]`, `11[\+]`,
+allows specifying a range of versions. (allowed values `8[+]`, `11[\+]`,
`17[+]`, `18[\+]`, `19[+]`, `20[\+]`, `21[+]`, `22[\+]`, `22[+]`)
`JAVA_OS`::
@@ -1984,7 +1984,7 @@ If the `findplist` argument is provided then contents of the `findlib` target di
If the `ldconfig` argument is provided then OCaml's [.filename]#ld.conf# file
will be automatically processed. When `dune` is used Dune may install stublibs
in site-lib package directory(ies) or in a single directory below `DUNE_LIBDIR` site-lib directory.
-Set if your port installs shared libraries into ocaml
+Set if the port installs shared libraries into ocaml
If the `run` argument is provided add ocamlc to `RUN_DEPENDS`.