Readme.txt vs. README.txt

Ho appena creato un progetto in Github, ho apportato le mie modifiche, ecc. Questo mi ha fatto meravigliare: vedo principalmente README.txt nei progetti opensource e il file che ho modificato era Readme.txt. È una sorta di standardizzazione o avrei dovuto lasciarlo così com'è?

Le lettere maiuscole si distinguono e rendono il file facilmente visibile, il che ha senso perché è probabilmente la prima cosa che un nuovo utente vorrebbe guardare. (O almeno, avrebbe dovuto guardare ...) Come altri hanno già detto, i nomi dei file che iniziano con una lettera maiuscola verranno elencati prima dei nomi minuscoli nell'ordinamento ASCIIbetical ( LC_COLLATE=C) che aiuta a rendere il file visibile a prima vista.

Il READMEfile fa parte di un gruppo di file che un utente di un pacchetto software gratuito si aspetterebbe di trovare. Altri sono INSTALL(istruzioni per la creazione e l'installazione del software), AUTHORS(elenco dei collaboratori), COPYING(testo della licenza), HACKING(come iniziare a contribuire, magari includendo un elenco TODO dei punti di partenza), NEWS(modifiche recenti) o ChangeLog(principalmente ridondanti con sistemi di controllo versione).

Questo è ciò che gli standard di codifica GNU hanno da dire sul READMEfile.

La distribuzione dovrebbe contenere un file denominato READMEcon una panoramica generale del pacchetto:

• il nome del pacchetto;
• il numero di versione del pacchetto o fare riferimento a dove nel pacchetto è possibile trovare la versione;
• una descrizione generale di ciò che fa il pacchetto;
• un riferimento al file INSTALL, che dovrebbe a sua volta contenere una spiegazione della procedura di installazione;
• una breve spiegazione di eventuali directory o file di alto livello insoliti, o altri suggerimenti per i lettori per orientarsi nella fonte;
• un riferimento al file che contiene le condizioni di copia. La GNU GPL, se usata, dovrebbe trovarsi in un file chiamato COPYING. Se si utilizza GNU LGPL, dovrebbe trovarsi in un file chiamato COPYING.LESSER.

Dal momento che è sempre bene cercare la minima sorpresa dei tuoi utenti, dovresti seguire questa convenzione a meno che non ci siano validi motivi per deviare. Nel mondo UNIX, le estensioni di file venivano tradizionalmente usate con parsimonia, quindi il nome canonico del file è READMEprivo di suffisso. Ma la maggior parte degli utenti probabilmente non avrebbe problemi a capire che un file chiamato README.txtha lo stesso significato. Se il file è scritto in Markdown , anche un nome di file simile README.mdpotrebbe essere ragionevole. Evita di usare linguaggi di markup più complicati come HTML inREADMEfile, tuttavia, perché dovrebbe essere comodo da leggere su un terminale di solo testo. È possibile indirizzare gli utenti al manuale del software o alla sua documentazione online, che potrebbe essere scritta in un formato più sofisticato, per i dettagli del READMEfile.

Tradizionalmente il file era chiamato README in maiuscolo perché gli ambienti della riga di comando che usano l'ordinamento alfabetico avrebbero posto il file in cima. Questo li rende facilmente visibili nelle grandi directory.

Molto probabilmente è un passaggio dal mondo Unix / Linux in cui scaricare fonti e quindi creare il software. Avere file come README e INSTALL nella parte superiore della vista "elenco contenuti directory" semplifica la visualizzazione della loro presenza, anziché dover sfogliare l'intero contenuto da un'interfaccia della riga di comando. Lo stesso principio di base funziona anche per github (e in realtà funziona anche nelle interfacce GUI, vieni a pensarci, quindi potrebbe comunque avere valore)

In nessun caso una regola difficile, ma molto probabilmente qualcosa che tutti stanno facendo come un'abitudine perché altri progetti lo stanno facendo. A meno che non ci sia una ragione esplicita di NON farlo, probabilmente dovresti usare tutti i tappi solo perché vedrai che viene usato in quel modo in molti altri progetti. È anche la denominazione predefinita utilizzata da Github quando si crea un nuovo repository.

README è solitamente scritto in maiuscolo. In questo modo il lscomando Unix posizionava il file vicino all'inizio dell'elenco di directory (le lettere maiuscole vengono prima delle lettere minuscole nell'ordinamento ASCII).