On 2017-11-08 08:10 AM, Jim Meyering wrote:
On Tue, Nov 7, 2017 at 11:51 PM, Assaf Gordon <[email protected]> wrote:
Github offers an option of creating an "issue template"
that will be shown whenever someone opens a new issue.
That sounds like a fine idea.
I'm attaching two drafts: one will be shown upon opening a new issue,
the other upon opening a "pull request".
They are a mishmash of various paragraphs from the README files and website.
There is some overlap between them, but I figured it's better to show
as much relevant information immediately than to send the user
over to more links.
To see how these work, visit this dummy project page:
https://github.com/agordon/cu-github-test
and try to create a new issue (or send a pull request).
Once we agree on the text I'll send a proper patch.
Comments welcomed.
- assaf
# Reporting GNU Coreutils Issues
Please **do not** send pull-requests or open new issues on Github.
* Send general questions or suggestions to: [email protected] .
* Send bugs reports to: [email protected] .
## Bug reports
Before reporting a new bug, please check the following resources:
* Coreutils FAQ: https://www.gnu.org/software/coreutils/faq/coreutils-faq.html
* Coreutils Gotchas: https://www.pixelbeat.org/docs/coreutils-gotchas.html
contains a list of some quirks and unexpected behaviour (which are often
mistaken for bugs).
* Online Manual:
https://www.gnu.org/software/coreutils/manual/html_node/index.html
* Search the archives for previous questions and answers:
* Coreutils Mailing list (General usage and advice):
https://lists.gnu.org/archive/html/coreutils/
* Bug reports Mailing List:
https://lists.gnu.org/archive/html/bug-coreutils/
* Open Bugs: https://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=coreitils
* Translation related issues:
https://translationproject.org/domain/coreutils.html
## Effective bug reports
* Include a descriptive subject line (e.g. the program with which
you experience a problem, and what the problem is).
* Include the version of the program (e.g. the output of `PROG --version`).
* Include the operating system and the type of hardware you are using
(e.g. the output of `uname -a`).
* Include the exact command and parameters you have used.
* Clearly explain what is the output you expected to get, and what is
the actual result you encountered.
* Include as much information as possible to reproduce the problem.
If the problem happens on a very large input file, try to provide
a minimal example (a subset of the input file) that still causes the problem.
*Do not* include attachments over 40kB.
## Mailing List Etiquette
When sending messages to [email protected] or [email protected] :
* Send messages as plain text.
* Do not send messages encoded as HTML nor encoded as base64 MIME nor
included as multiple formats.
* Avoid sending large messages, such as log files, system call trace
output, and other content resulting in messages over about 40 kB.
* Avoid sending screenshots (e.g. PNG files). When reporting errors
you encounter on the terminal, copy and paste the text to your message.
<!--
Copyright (C) 2017 Free Software Foundation, Inc.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
-->
# Contributing to GNU Coreutils
GNU Coreutils welcomes contributions.
Please *do not* send pull-requests or open new issues on Github.
See "hacking resources" below for recommended alternatives.
* Send general questions or suggestions to: [email protected] .
* Send bugs reports to: <[email protected]>
Before sending the bug, please consult the FAQ and Mailing list
archives (see below). Often these perceived bugs are simply due to
wrong program usage.
Please remember that development of Coreutils is a volunteer effort,
and you can also contribute to its development. For information about
contributing to the GNU Project, please read
[How to help GNU](https://www.gnu.org/help/].
## Getting Help
* Coreutils FAQ: https://www.gnu.org/software/coreutils/faq/coreutils-faq.html
* Coreutils Gotchas: https://www.pixelbeat.org/docs/coreutils-gotchas.html
contains a list of some quirks and unexpected behaviour (which are often
mistaken for bugs).
* Online Manual:
https://www.gnu.org/software/coreutils/manual/html_node/index.html
* Search the archives for previous questions and answers:
* Coreutils Mailing list (General usage and advice):
https://lists.gnu.org/archive/html/coreutils/
* Bug reports Mailing List:
https://lists.gnu.org/archive/html/bug-coreutils/
* Open Bugs: https://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=coreitils
* Translation related issues:
https://translationproject.org/domain/coreutils.html
## Mailing List Etiquette
When sending messages to [email protected] or [email protected] :
* Send messages as plain text.
* Do not send messages encoded as HTML nor encoded as base64 MIME nor
included as multiple formats.
* Include a descriptive subject line.
* Avoid sending large messages, such as log files, system call trace
output, and other content resulting in messages over about 40 kB.
* Avoid sending screenshots (e.g. PNG files). When reporting errors
you encounter on the terminal, copy and paste the text to your message.
## Hacking resources
files contain information about hacking and contributing to GNU coreutils:
https://git.savannah.gnu.org/cgit/coreutils.git/tree/HACKING
https://git.savannah.gnu.org/cgit/coreutils.git/tree/README-hacking
Please read them first.
Before suggesting a new feature, read the list of rejected features requests:
https://www.gnu.org/software/coreutils/rejected_requests.html
*Do not* send pull-requests on github.
Send a patch as an email attachment to [email protected] (for new features)
or [email protected] (for bug fixes).
Patches can be generated with `git format-patch` (the HACKING links above
provide
examples of generating a patch).
## Copyright Assignment
If your change is significant (i.e., if it adds more than ~10 lines),
then you'll have to have a copyright assignment on file with the FSF.
To learn more see https://www.gnu.org/licenses/why-assign.html .
The HACKING file (above) contains more details about how to initial
the copyright assignment process. Coreutils maintainers can also help
in this matter.
<!--
Copyright (C) 2017 Free Software Foundation, Inc.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
-->
