~sircmpwn/sr.ht-discuss

3 3

Re: Markdown, readmes and project pages.

Details
Message ID
<CJBGFL2NDNNM.2MFAF9IU2SOWG@taiga>
DKIM signature
pass
Download raw message
The answer is no. This is not the first time this has come up. You
should move your repo towards one of the established standard names for
this file.

Re: Markdown, readmes and project pages.

Details
Message ID
<CJBUK2ZM0O2X.184F4ZX7IZWND@grinningcatface>
In-Reply-To
<CJBGFL2NDNNM.2MFAF9IU2SOWG@taiga> (view parent)
DKIM signature
pass
Download raw message
On Sat Apr 16, 2022 at 2:36 AM EDT, Drew DeVault wrote:
> The answer is no. This is not the first time this has come up. You
> should move your repo towards one of the established standard names for
> this file.

Show me the standard and I will happily oblige. (I would actually be
genuinely happy about this.) Otherwise, convention is not standard, so
we should at least do the bare minimum to support slight variations.

-- 
DJ Chase
They, Them, Theirs

Re: Markdown, readmes and project pages.

Details
Message ID
<CJBUX0XGKF4Z.3S3ZJLMRQELOP@Archetype>
In-Reply-To
<CJBUK2ZM0O2X.184F4ZX7IZWND@grinningcatface> (view parent)
DKIM signature
pass
Download raw message
On Sat Apr 16, 2022 at 7:40 PM CEST, DJ Chase wrote:
> Show me the standard and I will happily oblige. (I would actually be
> genuinely happy about this.)

AFAICT this is adapted from GNU's "Release packing" standard where one
would usually pack the entire project tree and the README would then
serve the functions described here[0]. It's just useful to also show
these information to people checking out a repo as it contains the most
relevant information.

[0]: https://www.gnu.org/prep/standards/standards.html#index-README-file

--
Moritz Poldrack
https://moritz.sh

Re: Markdown, readmes and project pages.

Details
Message ID
<CJBVMLPU7MGF.3DYU8TJP83WTU@grinningcatface>
In-Reply-To
<CJBUX0XGKF4Z.3S3ZJLMRQELOP@Archetype> (view parent)
DKIM signature
pass
Download raw message
On Sat Apr 16, 2022 at 1:57 PM EDT, Moritz Poldrack wrote:
> On Sat Apr 16, 2022 at 7:40 PM CEST, DJ Chase wrote:
> > Show me the standard and I will happily oblige. (I would actually be
> > genuinely happy about this.)
>
> AFAICT this is adapted from GNU's "Release packing" standard where one
> would usually pack the entire project tree and the README would then
> serve the functions described here[0].
>
> [0]: https://www.gnu.org/prep/standards/standards.html#index-README-file

That document also specifies that Emacs is better than Vi. If we are
going by that standard, shouldn't we also support org-mode files? This
was requested in a somewhat-recent email IIRC. Also, the GNU Release
Packaging standard says that the file should be "README", so we should
drop support for "README.md" then.

On 2021-06-01?, GNU wrote:
>> When a feature is used only by users (not by programs or command
>> files), and it is done poorly in Unix, feel free to replace it
>> completely with something totally different and better. (For example,
>> vi is replaced with Emacs.)

Additionally, ESR's Software Release Practice HOWTO[1] says the
following about readme files:
>> Have a file called README or READ.ME that is a roadmap of your source
>> distribution. By ancient convention, this is the first file intrepid
>> explorers will read after unpacking the source.

A style guide from GNU and one from tldp.org seem roughly-equally
authoritive, especially since neither are actual standards. So, to
support "one of the established standard names", shouldn't we also
support "READ.ME" and possibly "READ.ME.md"?

> It's just useful to also show
> these information to people checking out a repo as it contains the most
> relevant information.

I agree, which is why we should try to find readmes if the first check
fails. Consider the Rule Of Repare[2]:
>> Rule of Repair: Repair what you can — but when you must fail, fail
>> noisily and as soon as possible.
>> 
>> Software should be transparent in the way that it fails, as well as
>> in normal operation. It's best when software can cope with unexpected
>> conditions by adapting to them, but the worst kinds of bugs are those
>> in which the repair doesn't succeed and the problem quietly causes
>> corruption that doesn't show up until much later.
>> 
>> Therefore, write your software to cope with incorrect inputs and its
>> own execution errors as gracefully as possible. But when it cannot,
>> make it fail in a way that makes diagnosis of the problem as easy as
>> possible.
>> 
>> Consider also Postel's Prescription:[10] “Be liberal in what you
>> accept, and conservative in what you send”.

[1]: https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme
[2]: http://www.catb.org/esr/writings/taoup/html/ch01s06.html#id2878538

-- 
DJ Chase
They, Them, Theirs
Reply to thread Export thread (mbox)