mirror of
https://codeberg.org/guix/guix.git
synced 2026-01-25 03:55:08 -06:00
Compare commits
4 commits
83230b23e3
...
03a650d10a
| Author | SHA1 | Date | |
|---|---|---|---|
|
03a650d10a | ||
|
|
8fa2d547bb | ||
|
|
556bfa3ddf | ||
|
|
3fa3df499c |
1 changed files with 20 additions and 284 deletions
|
|
@ -1950,33 +1950,15 @@ keyword parameters for procedures that take more than four parameters.
|
|||
|
||||
Development is done using the Git distributed version control system.
|
||||
Thus, access to the repository is not strictly necessary. We welcome
|
||||
contributions in one of the following forms:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@cindex pull request, for contributions
|
||||
As a @dfn{pull request} (PR) at
|
||||
@url{https://codeberg.org/guix/guix/pulls/}. This is now the preferred
|
||||
form.
|
||||
|
||||
@item
|
||||
Until December 31st, 2025@footnote{This date is the result of a decision
|
||||
made collectively in
|
||||
contributions as @dfn{pull requests} (PR) at
|
||||
@url{https://codeberg.org/guix/guix/pulls/}@footnote{Before January 1st,
|
||||
2026, changes would be submitted by email to
|
||||
@email{guix-patches@@gnu.org} and could be
|
||||
@uref{https://issues.guix.gnu.org, browsed online}. In accordance with
|
||||
@uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/002-codeberg.md,
|
||||
Guix Consensus Document 002} in May 2025.}, you may also send patches as
|
||||
produced by @code{git format-patch} to the @email{guix-patches@@gnu.org}
|
||||
mailing list (@pxref{Submitting patches to a project,,, git, Git User
|
||||
Manual}).
|
||||
Guix Consensus Document 002}, this method is longer supported.}.
|
||||
|
||||
This mailing list is backed by a Debbugs instance, which allows us to
|
||||
keep track of submissions (@pxref{Tracking Bugs and Changes}).
|
||||
Each message sent to that mailing list gets a new tracking number
|
||||
assigned; people can then follow up on the submission by sending email
|
||||
to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
|
||||
is the tracking number (@pxref{Sending a Patch Series}).
|
||||
@end itemize
|
||||
|
||||
Either way, contributors are encouraged to take a moment to set some Git
|
||||
Contributors are encouraged to take a moment to set some Git
|
||||
repository options (@pxref{Configuring Git}) first, which can improve
|
||||
the readability of patches. Seasoned Guix developers may also want to
|
||||
look at the section on commit access (@pxref{Commit Access}).
|
||||
|
|
@ -2143,36 +2125,13 @@ guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master --disable-auth
|
|||
|
||||
@end enumerate
|
||||
|
||||
When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
|
||||
a subject, if your patch is to be applied on a branch other than
|
||||
@code{master}, say @code{core-updates}, specify it in the subject like
|
||||
@samp{[PATCH core-updates] @dots{}}.
|
||||
|
||||
You may use your email client, the @command{git send-email} command
|
||||
(@pxref{Sending a Patch Series}) or the @command{mumi send-email}
|
||||
command (@pxref{Debbugs User Interfaces}). We prefer to get patches in
|
||||
plain text messages, either inline or as MIME attachments. You are
|
||||
advised to pay attention if your email client changes anything like line
|
||||
breaks or indentation which could potentially break the patches.
|
||||
|
||||
Expect some delay when you submit your very first patch to
|
||||
@email{guix-patches@@gnu.org}. You have to wait until you get an
|
||||
acknowledgement with the assigned tracking number. Future acknowledgements
|
||||
should not be delayed.
|
||||
|
||||
When a bug is resolved, please close the thread by sending an email to
|
||||
@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
|
||||
|
||||
@menu
|
||||
* Configuring Git::
|
||||
* Sending a Patch Series::
|
||||
@end menu
|
||||
|
||||
@node Configuring Git
|
||||
@subsection Configuring Git
|
||||
@cindex git configuration
|
||||
@cindex @code{git format-patch}
|
||||
@cindex @code{git send-email}
|
||||
|
||||
If you have not done so already, you may wish to set a name and email
|
||||
that will be associated with your commits (@pxref{telling git your name,
|
||||
|
|
@ -2192,166 +2151,6 @@ changes was already submitted for review. If you have a
|
|||
@file{commit-msg} hook of your own you would like to use with Guix, you
|
||||
can place it under the @file{.git/hooks/commit-msg.d/} directory.
|
||||
|
||||
@node Sending a Patch Series
|
||||
@subsection Sending a Patch Series
|
||||
@cindex patch series
|
||||
@cindex @code{git send-email}
|
||||
@cindex @code{git format-patch}
|
||||
|
||||
@quotation Warning
|
||||
This section is about contributing code by sending patches by email.
|
||||
This option is supported until December 31st, 2025, but we recommend
|
||||
getting familiar with the @dfn{pull request} workflow, which will become
|
||||
the norm after that date. @xref{Submitting Patches}, for more info.
|
||||
@end quotation
|
||||
|
||||
@unnumberedsubsubsec Single Patches
|
||||
@anchor{Single Patches}
|
||||
The @command{git send-email} command is the best way to send both single
|
||||
patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
|
||||
list. Sending patches as email attachments may make them difficult to
|
||||
review in some mail clients, and @command{git diff} does not store commit
|
||||
metadata.
|
||||
|
||||
@quotation Note
|
||||
The @command{git send-email} command is provided by the @code{send-email}
|
||||
output of the @code{git} package, i.e. @code{git:send-email}.
|
||||
@end quotation
|
||||
|
||||
The following command will create a patch email from the latest commit,
|
||||
open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
|
||||
the Guix mailing list to be reviewed and merged. Assuming you have
|
||||
already configured Git according to @xref{Configuring Git}, you can
|
||||
simply use:
|
||||
|
||||
@example
|
||||
$ git send-email --annotate -1
|
||||
@end example
|
||||
|
||||
@quotation Tip
|
||||
To add a prefix to the subject of your patch, you may use the
|
||||
@option{--subject-prefix} option. The Guix project uses this to
|
||||
specify that the patch is intended for a branch or repository
|
||||
other than the @code{master} branch of
|
||||
@url{https://codeberg.org/guix/guix.git}.
|
||||
|
||||
@example
|
||||
git send-email --annotate --subject-prefix='PATCH core-updates' -1
|
||||
@end example
|
||||
@end quotation
|
||||
|
||||
The patch email contains a three-dash separator line after the commit
|
||||
message. You may ``annotate'' the patch with explanatory text by adding
|
||||
it under this line. If you do not wish to annotate the email, you may
|
||||
drop the @option{--annotate} option.
|
||||
|
||||
If you need to send a revised patch, don't resend it like this or send
|
||||
a ``fix'' patch to be applied on top of the last one; instead, use
|
||||
@command{git commit --amend} or @url{https://git-rebase.io,
|
||||
@command{git rebase}} to modify the commit, and use the
|
||||
@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
|
||||
flag with @command{git send-email}.
|
||||
|
||||
@example
|
||||
$ git commit --amend
|
||||
$ git send-email --annotate -v@var{REVISION} \
|
||||
--to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
|
||||
@end example
|
||||
|
||||
@quotation Note
|
||||
Due to an apparent bug in @command{git send-email},
|
||||
@option{-v @var{REVISION}} (with the space) will not work; you
|
||||
@emph{must} use @option{-v@var{REVISION}}.
|
||||
@end quotation
|
||||
|
||||
You can find out @var{ISSUE_NUMBER} either by searching on the mumi
|
||||
interface at @url{https://issues.guix.gnu.org} for the name of your patch or
|
||||
reading the acknowledgement email sent automatically by Debbugs in
|
||||
reply to incoming bugs and patches, which contains the bug number.
|
||||
|
||||
@unnumberedsubsubsec Notifying Teams
|
||||
@anchor{Notifying Teams}
|
||||
@cindex teams
|
||||
If your git checkout has been correctly configured (@pxref{Configuring
|
||||
Git}), the @command{git send-email} command will automatically notify
|
||||
the appropriate team members, based on the scope of your changes. This
|
||||
relies on the @file{etc/teams.scm} script, which can also be invoked
|
||||
manually if you do not use the preferred @command{git send-email}
|
||||
command to submit patches. To list the available actions of the script,
|
||||
you can invoke it via the @command{etc/teams.scm help} command. For
|
||||
more information regarding teams, @pxref{Teams}.
|
||||
|
||||
@quotation Note
|
||||
On foreign distros, you might have to use @command{./pre-inst-env git
|
||||
send-email} for @file{etc/teams.scm} to work.
|
||||
@end quotation
|
||||
|
||||
@unnumberedsubsubsec Multiple Patches
|
||||
@anchor{Multiple Patches}
|
||||
@cindex cover letter
|
||||
While @command{git send-email} alone will suffice for a single
|
||||
patch, an unfortunate flaw in Debbugs means you need to be more
|
||||
careful when sending multiple patches: if you send them all to the
|
||||
@email{guix-patches@@gnu.org} address, a new issue will be created
|
||||
for each patch!
|
||||
|
||||
When sending a series of patches, it's best to send a Git ``cover
|
||||
letter'' first, to give reviewers an overview of the patch series.
|
||||
We can create a directory called @file{outgoing} containing both
|
||||
our patch series and a cover letter called @file{0000-cover-letter.patch}
|
||||
with @command{git format-patch}.
|
||||
|
||||
@example
|
||||
$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
|
||||
--cover-letter
|
||||
@end example
|
||||
|
||||
@quotation Note
|
||||
@code{git format-patch} accepts a wide range of
|
||||
@uref{https://git-scm.com/docs/gitrevisions, revision range} specifiers.
|
||||
For example, if you are working in a branch, you could select all commits
|
||||
in your branch starting at @code{master}.
|
||||
|
||||
@example
|
||||
$ git format-patch master..@var{MY_BRANCH} -o outgoing \
|
||||
--cover-letter
|
||||
@end example
|
||||
@end quotation
|
||||
|
||||
We can now send @emph{just} the cover letter to the
|
||||
@email{guix-patches@@gnu.org} address, which will create an issue
|
||||
that we can send the rest of the patches to.
|
||||
|
||||
@example
|
||||
$ git send-email outgoing/0000-cover-letter.patch --annotate
|
||||
$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
|
||||
@end example
|
||||
|
||||
Ensure you edit the email to add an appropriate subject line and
|
||||
blurb before sending it. Note the automatically generated shortlog
|
||||
and diffstat below the blurb.
|
||||
|
||||
Once the Debbugs mailer has replied to your cover letter email, you
|
||||
can send the actual patches to the newly-created issue address.
|
||||
|
||||
@example
|
||||
$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
|
||||
$ rm -rf outgoing # we don't need these anymore
|
||||
@end example
|
||||
|
||||
Thankfully, this @command{git format-patch} dance is not necessary
|
||||
to send an amended patch series, since an issue already exists for
|
||||
the patchset.
|
||||
|
||||
@example
|
||||
$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
|
||||
--to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
|
||||
@end example
|
||||
|
||||
If need be, you may use @option{--cover-letter --annotate} to send
|
||||
another cover letter, e.g. for explaining what's changed since the last
|
||||
revision, and why these changes are necessary.
|
||||
|
||||
@node Tracking Bugs and Changes
|
||||
@section Tracking Bugs and Changes
|
||||
|
||||
|
|
@ -2362,31 +2161,26 @@ patch submissions and topic branches.
|
|||
* The Issue Tracker:: The official bug and patch tracker.
|
||||
* Managing Patches and Branches:: How changes to Guix are managed.
|
||||
* Debbugs User Interfaces:: Ways to interact with Debbugs.
|
||||
* Debbugs Usertags:: Tag reports with custom labels.
|
||||
* Cuirass Build Notifications:: Be alerted of any breakage via RSS feeds.
|
||||
@end menu
|
||||
|
||||
@node The Issue Tracker
|
||||
@subsection The Issue Tracker
|
||||
|
||||
@cindex bug reports, tracking
|
||||
@cindex patch submissions, tracking
|
||||
@cindex issue tracking
|
||||
@cindex email workflow, deprecated
|
||||
@cindex issue tracker, for the email workflow
|
||||
@cindex Debbugs, issue tracking system
|
||||
Bug reports (@dfn{issues}) and patch submissions (@dfn{pull requests})
|
||||
are currently tracked at the @uref{https://codeberg.org/guix/guix,
|
||||
project's home at Codeberg}.
|
||||
|
||||
Before May 25th, 2025, bug reports and patches were exclusively tracked
|
||||
using the Debbugs instance at @uref{https://bugs.gnu.org}; it may still
|
||||
be used for these purposes until December 31st, 2025, after which
|
||||
Codeberg will become the sole option to report new bugs and propose new
|
||||
changes@footnote{Check out
|
||||
Before January 1st, 2026, bug reports and patches were tracked using the
|
||||
Debbugs instance at @uref{https://bugs.gnu.org}, which can also be
|
||||
browsed at @uref{https://issues.guix.gnu.org}. This has been
|
||||
discontinued and Codeberg is now the sole option to report new bugs and
|
||||
propose new changes@footnote{Check out
|
||||
@uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/002-codeberg.md,
|
||||
Guix Consensus Document 002} for details on this decision.}. With
|
||||
Debbugs, bug reports are sent by email to @email{bug-guix@@gnu.org} and
|
||||
patches are sent to @email{guix-patches@@gnu.org} (@pxref{Submitting
|
||||
Patches}).
|
||||
Guix Consensus Document 002} for details on this decision.}.
|
||||
|
||||
@node Managing Patches and Branches
|
||||
@subsection Managing Patches and Branches
|
||||
|
|
@ -2498,11 +2292,10 @@ only then should the merge requests be created, as documented earlier.
|
|||
|
||||
@quotation Warning
|
||||
This section is about bug reports and patches sent by email to
|
||||
@uref{https://issues.guix.gnu.org, Debbugs}. This option is supported
|
||||
until December 31st, 2025, after which
|
||||
@uref{https://codeberg.org/guix/guix, Codeberg} will be the only
|
||||
interface for submitting bug reports and changes. @xref{Submitting
|
||||
Patches}, for more info.
|
||||
@uref{https://issues.guix.gnu.org, Debbugs}, which is discontinued.
|
||||
Since January 1st, 2026, bug reports and patches are submitted as issues
|
||||
and pull requests on @uref{https://codeberg.org/guix/guix, Codeberg}.
|
||||
@xref{Submitting Patches}, for more info.
|
||||
@end quotation
|
||||
|
||||
@subsubsection Web interface
|
||||
|
|
@ -2691,63 +2484,6 @@ used.
|
|||
@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
|
||||
this nifty tool!
|
||||
|
||||
@node Debbugs Usertags
|
||||
@subsection Debbugs Usertags
|
||||
|
||||
@cindex usertags, for debbugs
|
||||
@cindex Debbugs usertags
|
||||
Debbugs provides a feature called @dfn{usertags} that allows any user to
|
||||
tag any bug with an arbitrary label. Bugs can be searched by usertag,
|
||||
so this is a handy way to organize bugs@footnote{The list of usertags is
|
||||
public information, and anyone can modify any user's list of usertags,
|
||||
so keep that in mind if you choose to use this feature.}. If you use
|
||||
Emacs Debbugs, the entry-point to consult existing usertags is the
|
||||
@samp{C-u M-x debbugs-gnu-usertags} procedure. To set a usertag, press
|
||||
@samp{C} while consulting a bug within the *Guix-Patches* buffer opened
|
||||
with @samp{C-u M-x debbugs-gnu-bugs} buffer, then select @code{usertag}
|
||||
and follow the instructions.
|
||||
|
||||
For example, to view all the bug reports (or patches, in the case of
|
||||
@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux}
|
||||
for the user @code{guix}, open a URL like the following in a web
|
||||
browser:
|
||||
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.
|
||||
|
||||
For more information on how to use usertags, please refer to the
|
||||
documentation for Debbugs or the documentation for whatever tool you use
|
||||
to interact with Debbugs.
|
||||
|
||||
In Guix, we are experimenting with usertags to keep track of
|
||||
architecture-specific issues, as well as reviewed ones. To facilitate
|
||||
collaboration, all our usertags are associated with the single user
|
||||
@code{guix}. The following usertags currently exist for that user:
|
||||
|
||||
@table @code
|
||||
|
||||
@item powerpc64le-linux
|
||||
The purpose of this usertag is to make it easy to find the issues that
|
||||
matter most for the @code{powerpc64le-linux} system type. Please assign
|
||||
this usertag to bugs or patches that affect @code{powerpc64le-linux} but
|
||||
not other system types. In addition, you may use it to identify issues
|
||||
that for some reason are particularly important for the
|
||||
@code{powerpc64le-linux} system type, even if the issue affects other
|
||||
system types, too.
|
||||
|
||||
@item reproducibility
|
||||
For issues related to reproducibility. For example, it would be
|
||||
appropriate to assign this usertag to a bug report for a package that
|
||||
fails to build reproducibly.
|
||||
|
||||
@item reviewed-looks-good
|
||||
You have reviewed the series and it looks good to you (LGTM).
|
||||
|
||||
@end table
|
||||
|
||||
If you're a committer and you want to add a usertag, just start using it
|
||||
with the @code{guix} user. If the usertag proves useful to you,
|
||||
consider updating this section of the manual so that others will know
|
||||
what your usertag means.
|
||||
|
||||
@node Cuirass Build Notifications
|
||||
@subsection Cuirass Build Notifications
|
||||
|
||||
|
|
@ -3249,7 +2985,7 @@ to that commit message.
|
|||
|
||||
If you are not a committer, you can help others find a @emph{series} you
|
||||
have reviewed more easily by adding a @code{reviewed-looks-good} usertag
|
||||
for the @code{guix} user (@pxref{Debbugs Usertags}).
|
||||
for the @code{guix} user.
|
||||
|
||||
@node Updating the Guix Package
|
||||
@section Updating the Guix Package
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue