diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -228,9 +228,10 @@ Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. -This is done with the man:diff[1] command. -The preferred man:diff[1] format for submitting patches is the unified output format generated by `diff -u`. +This can be done manually with the man:diff[1] command or by making use of the diff feature built into man:git[1]. + +When using man:diff[1], the preferred format for submitting patches is the unified output format generated by `diff -u`. [source,shell] .... @@ -248,12 +249,31 @@ See man:diff[1] for more information. -Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report. +man:git[1] can generate a unified diff and include more contextual information through its `-U` flag: + +[source,shell] +.... +% git format-patch -U9999 origin/main +.... + +This will generate a set of patches containing all your changes in contrast to the main branch. + +Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report at link:https://bugs.freebsd.org[Bugzilla]. _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including `[PATCH]` in the synopsis of the report. -If you feel it appropriate (for example you have added, deleted, or renamed files), bundle your changes into a `tar` file. -Archives created with man:shar[1] are also welcome. +If your work bundles significant changes (for example you have added, deleted, or renamed files), it is recommended to upload your changes to a service like link:https://reviews.freebsd.org[Phabricator] for review. You can do so by adding a comment to your PR listing the URL to the review. +Vice versa, it is helpful and recommended to reference the link to the PR on Phabricator as well. + +To help the review process, it is possible to generate a single diff file [.filename]#patch.diff# through + +[source,shell] +... +git diff -U9999 main origin/main > patch.diff +... + +which can then be uploaded to link:https://reviews.freebsd.org[Phabricator] for public review. +A bug report should still be filed on Bugzilla when uploading to Phabricator and it is recommended to link the Phabricator review in the bug report. If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. @@ -264,8 +284,7 @@ === New Code or Major Value-Added Packages -In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or upload them to a web or FTP site for other people to access. -If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. +In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either upload them to link:https://reviews.freebsd.org[Phabricator], or use a service like link:https://github.com[Github] link:https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests[pull requests] for other people to access and review. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. @@ -370,7 +389,8 @@ * *Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers. * *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. -You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. +You are not expected to provide general support (but we welcome it if you choose to do so). +What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. * *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. You will need to investigate, find, and fix these bugs when they are reported.