diff --git a/docs/CONTRIBUTING-de.md b/docs/CONTRIBUTING-de.md index d5700a895a7ce..c6acc3c1503e1 100644 --- a/docs/CONTRIBUTING-de.md +++ b/docs/CONTRIBUTING-de.md @@ -1,58 +1,71 @@ *[Diese Anleitung in anderen Sprachen](../README.md#translations)* + ## Lizenzvereinbarung für Mitwirkende + Durch Deine Mitwirkung akzeptierst Du die [Lizenz](../LICENSE) dieses Repositorys. + ## Verhaltenskodex für Mitwirkende + Durch Deine Mitwirkung verpflichtest Du Dich, dem [Verhaltenskodex](CODE_OF_CONDUCT-de.md) dieses Repositorys zu folgen. ([translations](../README.md#translations)) + ## Kurzfassung + 1. „Ein Link, um ein Buch auf einfache Weise herunterzuladen“ ist nicht immer ein Link zu einem *kostenlosen* Buch. Bitte füge nur kostenlose Inhalte hinzu. Vergewissere Dich, dass sie kostenlos sind. Wir akzeptieren keine Links zu Seiten, die *voraussetzen*, dass man sich mit einer funktionierenden E-Mail-Adresse registriert, um ein Buch herunterzuladen, aber wir heißen Seiten willkommen, die um (optionale) Eingaben von E-Mail-Adressen bitten. + 2. Du musst Dich nicht mit Git auskennen: Wenn Du etwas Interessantes gefunden hast, *das noch nicht in einer der Listen enthalten ist*, öffne bitte ein [Issue](https://github.com/EbookFoundation/free-programming-books/issues) mit Deinen Linkvorschlägen. - - Wenn Du Dich mit Git auskennst, erstelle einen Fork des Repositorys und sende einen Pull Request. + - Wenn Du Dich mit Git auskennst, erstelle einen Fork des Repositorys und sende einen Pull Request (PR). + 3. Wir führen 5 Arten von Listen. Achte darauf, die richtige zu wählen: - *Bücher*: PDF, HTML, ePub, eine auf gitbook.io basierende Seite, ein Git Repo etc. - *Kurse*: Ein Kurs beschreibt Lernmaterialien, die nicht in Buchform existieren. [Dies ist ein Kurs](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Interaktive Tutorials*: Eine interaktive Webseite, die den Benutzer Sourcecode oder Kommandos eingeben lässt und das Resultat auswertet (mit "auswerten" meinen wir nicht "bewerten"). z. B.: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Interaktive Tutorials*: Eine interaktive Webseite, die den Benutzer Sourcecode oder Kommandos eingeben lässt und das Resultat auswertet (mit "auswerten" meinen wir nicht "bewerten"). z. B.: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts und Screencasts*: Podcasts und Screencasts. - *Problem Sets & Competitive Programming*: Eine Webseite oder Software, die Dir die Möglichkeit gibt, Deine Programmierfähigkeiten durch die Lösung einfacher oder komplexer Problemstellungen auf die Probe zu stellen, mit oder ohne Code Review und mit oder ohne den Vergleich der Leistungen mit anderen Besuchern der Seite. 4. Stell sicher, dass Du den [Richtlinien](#richtlinien) folgst und die [Markdown Formatierung](#formatierung) der Dateien beachtest. -5. GitHub Actions werden Tests ausführen, um sicherzustellen, dass die Listen korrekt alphabetisiert sind und den Formatierungsregeln Folge geleistet wurde. Stell sicher, dass Deine Änderungen diese Tests bestehen. +5. GitHub Actions werden Tests ausführen, um sicherzustellen, dass die **Listen korrekt alphabetisiert sind** und den **Formatierungsregeln Folge geleistet wurde**. **Stell sicher**, dass Deine Änderungen diese Tests bestehen. + ### Richtlinien + - Stell sicher, dass ein Buch wirklich kostenlos ist. Vergewissere Dich noch einmal, falls nötig. Es hilft den Administratoren, wenn Du in Deinem PR beschreibst, warum Du der Ansicht bist, dass das jeweilige Buch kostenlos ist. - Wir nehmen keine Dateien auf, die auf Google Drive, Dropbox, Mega, Scribd, Issuu oder einer vergleichbaren Upload-Plattform liegen. - Füge die Links in alphabetischer Reihenfolge ein. Wenn Du einen fehlerhaft eingefügten Link findest, korrigiere bitte die Reihenfolge und öffne eine PR. - Wähle immer den Link der maßgeblichen Quelle aus (das heißt, dass die Website des Autors besser ist als die eines Redakteurs, welche wiederum besser wäre als die einer Drittanbieterseite) - + Keine File Hosting Plattformen (inklusive Links zu Dropbox, Google Drive u.ä.) -- Ein `https` Link sollte einem `http` Link immer vorgezogen werden -- solange sie auf dieselbe Domain und denselben Inhalt verweisen. + - Keine File Hosting Plattformen (inklusive Links zu Dropbox, Google Drive u.ä.) +- Ein `https` Link sollte einem `http` Link immer vorgezogen werden -- solange sie auf dieselbe Domain und denselben Inhalt verweisen. - Auf Root Domains sollte der abschließende Schrägstrich entfernt werden: `http://example.com` anstelle von `http://example.com/` - Wähle immer den kürzesten Link: `http://example.com/dir/` ist besser als `http://example.com/dir/index.html` - + Benutze keine URL-Verkürzer + - Benutze keine URL-Verkürzer - Wähle bevorzugt den Link zur aktuellsten Version anstatt eine konkrete Version zu verlinken: `http://example.com/dir/book/current/` ist besser als `http://example.com/dir/book/v1.0.0/index.html` - Wenn ein Link ein abgelaufenes oder selbst-signiertes Zertifikat nutzt oder ein anderes SSL Problem aufweist: - 1. *ersetze ihn* mit seinem `http` Gegenstück, wenn möglich (weil es auf Mobilgeräten kompliziert sein kann, Ausnahmen zuzulassen). - 2. *lass ihn wie er ist*, falls keine `http` Version verfügbar ist, auf den Link aber über `https` zugegriffen werden kann, indem man im Browser die Warnung ignoriert oder eine Ausnahme hinzufügt. - 3. *entferne ihn* anderenfalls. + 1. *ersetze ihn* mit seinem `http` Gegenstück, wenn möglich (weil es auf Mobilgeräten kompliziert sein kann, Ausnahmen zuzulassen). + 2. *lass ihn wie er ist*, falls keine `http` Version verfügbar ist, auf den Link aber über `https` zugegriffen werden kann, indem man im Browser die Warnung ignoriert oder eine Ausnahme hinzufügt. + 3. *entferne ihn* anderenfalls. - Wenn ein Link in verschiedenen Formaten existiert, füge einen separaten Link hinzu mit einem Hinweis zu jedem Format - Wenn ein Inhalt an mehreren Stellen im Internet verfügbar ist - + wähle den Link der maßgeblichen Quelle aus (das heißt, dass die Website des Autors besser ist als die eines Redakteurs, welche wiederum besser wäre als die einer Drittanbieterseite) - + wenn sie verschiedene Ausgaben verlinken und Du der Meinung bist, dass sich diese Ausgaben in einem Maße unterscheiden, dass man alle aufheben sollte, füge einen separaten Link hinzu mit einem Hinweis zu jeder Ausgabe (siehe [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353), um Dich an der Diskussion zur Formatierung zu beteiligen.) + - wähle den Link der maßgeblichen Quelle aus (das heißt, dass die Website des Autors besser ist als die eines Redakteurs, welche wiederum besser wäre als die einer Drittanbieterseite) + - wenn sie verschiedene Ausgaben verlinken und Du der Meinung bist, dass sich diese Ausgaben in einem Maße unterscheiden, dass man alle aufheben sollte, füge einen separaten Link hinzu mit einem Hinweis zu jeder Ausgabe (siehe [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353), um Dich an der Diskussion zur Formatierung zu beteiligen). - Bevorzuge atomare Commits (ein Commit pro Änderung), anstatt größere Commits zu machen. Es besteht keine Notwendigkeit, die Commits vor dem Abschicken des PR zu squashen. (Wir werden die Befolgung dieser Regel niemals erzwingen, da es sich hier nur um die Vermeidung von Unannehmlichkeiten für die Maintainer handelt) - Vermerke das Datum der Veröffentlichung im Titel, wenn es sich um ein älteres Buch handelt. -- Erfasse gegebenenfalls den Namen des oder der Autoren. Eine längere Liste von Autoren kann mit dem Zusatz "et al." gekürzt werden. -- Wenn das Buch noch nicht fertiggestellt ist und sich noch in Bearbeitung befindet, füge wie [unten](#in_process) beschrieben einen "in Bearbeitung" Hinweis hinzu. -- Wenn eine funktionierende E-Mail Adresse oder das Einrichten eines Benutzerkontos vor Aktivierung des Downloads erbeten wird, sollten angemessene Hinweise in Klammern angegeben werden, z. B.: `(E-Mail Adresse *erbeten*, nicht erforderlich)` +- Erfasse gegebenenfalls den Namen des oder der Autoren. Eine längere Liste von Autoren kann mit dem Zusatz "`et al.`" gekürzt werden. +- Wenn das Buch noch nicht fertiggestellt ist und sich noch in Bearbeitung befindet, füge wie [unten](#in_process) beschrieben einen "`in process`" Hinweis hinzu. +- Wenn eine funktionierende E-Mail Adresse oder das Einrichten eines Benutzerkontos vor Aktivierung des Downloads erbeten wird, sollten angemessene Hinweise in Klammern angegeben werden, z. B.: `(E-Mail Adresse *erbeten*, nicht erforderlich)`. + ### Formatierung + - Bei allen Listen handelt es sich um `.md` Dateien. Versuche bitte, Dir die [Markdown](https://guides.github.com/features/mastering-markdown/) Syntax anzueignen. Sie ist ganz einfach! - Alle Listen beginnen mit einem Inhaltsverzeichnis, in dem alle Abschnitte und Unterabschnitte verlinkt werden sollten. Bitte halte eine alphabetische Reihenfolge ein. - Abschnitte nutzen Überschriften der Ebene 3 (`###`), während Unterabschnitte die 4. Ebene (`####`) nutzen. Folgende Formatierungsregeln sollten eingehalten werden: + - `2` Leerzeilen zwischen dem letzten Link und einem neuen Abschnitt. - `1` Leerzeile zwischen der Überschrift und dem ersten Link eines Abschnitts. - `0` Leerzeilen zwischen zwei Links. @@ -60,103 +73,112 @@ Folgende Formatierungsregeln sollten eingehalten werden: Beispiel: - [...] - * [Ein tolles Buch](http://example.com/example.html) - (Leerzeile) - (Leerzeile) - ### Beispiel - (Leerzeile) - * [Noch ein tolles Buch](http://example.com/book.html) - * [Ein anderes Buch](http://example.com/other.html) +```text +[...] +* [Ein tolles Buch](http://example.com/example.html) + (Leerzeile) + (Leerzeile) +### Beispiel + (Leerzeile) +* [Noch ein tolles Buch](http://example.com/book.html) +* [Ein anderes Buch](http://example.com/other.html) +``` - Keine Leerzeichen zwischen `]` und `(` einfügen: -``` -FALSCH : * [Noch ein tolles Buch] (http://example.com/book.html) -RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) -``` + ```text + FALSCH : * [Noch ein tolles Buch] (http://example.com/book.html) + RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) + ``` - Wenn Du den Autor nennst, nutze ` - ` (einen mit Leerzeichen eingefassten Gedankenstrich): -``` -FALSCH : * [Noch ein tolles Buch](http://example.com/book.html)- John Doe -RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) - John Doe -``` + ```text + FALSCH : * [Noch ein tolles Buch](http://example.com/book.html)- John Doe + RICHTIG: * [Noch ein tolles Buch](http://example.com/book.html) - John Doe + ``` - Füge ein einzelnes Leerzeichen zwischen dem Link und seinem Dateiformat ein: -``` -FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)(PDF) -RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) (PDF) -``` + ```text + FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)(PDF) + RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) (PDF) + ``` - Der Autor wird vor dem Format genannt: -``` -FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)- (PDF) Jane Roe -RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + FALSCH : * [Ein sehr tolles Buch](https://example.org/book.pdf)- (PDF) Jane Roe + RICHTIG: * [Ein sehr tolles Buch](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Verschiedene Formate: -``` -FALSCH : * [Noch ein tolles Buch](http://example.com/)- John Doe (HTML) -FALSCH : * [Noch ein tolles Buch](https://downloads.example.org/book.html)- John Doe (download site) -RICHTIG: * [Noch ein tolles Buch](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + FALSCH : * [Noch ein tolles Buch](http://example.com/)- John Doe (HTML) + FALSCH : * [Noch ein tolles Buch](https://downloads.example.org/book.html)- John Doe (download site) + RICHTIG: * [Noch ein tolles Buch](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Nenne das Jahr der Veröffentlichung im Titel bei älteren Publikationen: -``` -FALSCH : * [Ein sehr tolles Buch](https://example.org/book.html) - Jane Roe - 1970 -RICHTIG: * [Ein sehr tolles Buch (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + FALSCH : * [Ein sehr tolles Buch](https://example.org/book.html) - Jane Roe - 1970 + RICHTIG: * [Ein sehr tolles Buch (1970)](https://example.org/book.html) - Jane Roe + ``` - -- Bücher in Bearbeitung: +- Bücher in Bearbeitung: + + ```text + RICHTIG: * [Wird bald ein tolles Buch sein](http://example.com/book2.html) - John Doe (HTML) (:construction: *in Bearbeitung*) + ``` -``` -RICHTIG: * [Wird bald ein tolles Buch sein](http://example.com/book2.html) - John Doe (HTML) (:construction: *in Bearbeitung*) -``` ### Hinweise Während die Grundlagen relativ einfach sind, existiert eine große Vielfalt von Ressourcen in unseren Listen. Es folgen einige Hinweise, wie wir mit dieser Vielfalt umgehen. + #### Metadaten Unsere Listen enthalten einen minimalen Satz an Metadaten: Titel, URLs, Autoren, Plattformen und Zugriffshinweise. + ##### Titel -- Keine erfundenen Titel. Wir versuchen, die Titel den Inhalten selbst zu entnehmen; Mitwirkende werden dazu ermahnt, sich keine Titel auszudenken oder redaktionell zu nutzen, falls dies vermieden werden kann. Eine Ausnahme bilden ältere Werke; wenn sie vor allem von historischem Interesse sind, kann das Hinzufügen einer Jahreszahl in Klammern den Nutzern helfen zu bestimmen, ob die Inhalte für sie nützlich sind. +- Keine erfundenen Titel. Wir versuchen, die Titel den Inhalten selbst zu entnehmen; Mitwirkende werden dazu ermahnt, sich keine Titel auszudenken oder redaktionell zu nutzen, falls dies vermieden werden kann. Eine Ausnahme bilden ältere Werke; wenn sie vor allem von historischem Interesse sind, kann das Hinzufügen einer Jahreszahl in Klammern den Nutzern helfen zu bestimmen, ob die Inhalte für sie nützlich sind. - Keine Titel, die NUR GROßBUCHSTABEN ENTHALTEN. Titelkapitalisierung ist normalerweise angemessen, aber im Zweifel nutze einfach die Formatierung der Originalquelle. + ##### URLs - Wir erlauben keine gekürzten URLs. - Sämtliche Tracking-Codes sind aus der URL zu entfernen. - Internationale URLs sollten entsprechend maskiert/escaped werden. Auch wenn Adressleisten in Browsern diese üblicherweise in Unicode darstellen, nutze bitte kopieren & einfügen. -- Sichere (https) URLs werden immer nicht-sicheren (http) URLs vorgezogen, wenn von der Quelle https implementiert wurde. +- Sichere (`https`) URLs werden immer nicht-sicheren (`http`) URLs vorgezogen, wenn von der Quelle HTTPS implementiert wurde. - Wir mögen keine URLs, die auf Webseiten zeigen, die den angegebenen Inhalt nicht bereitstellen, sondern stattdessen an andere Stelle umleiten. + ##### Urheber - Wir wollen alle Urheber kostenloser Inhalte angemessen nennen, inklusive eventueller Übersetzer! - For übersetzte Werke sollte der Autor des ursprünglichen Werks genannt werden. - Wir erlauben keine Links für Urheber. -- Für Sammlungen oder neu zusammengestellte Werke, benötigt der "Urheber" eventuell eine Beschreibung. Bücher von "GoalKicker" werden z. B. als "Zusammengestellt aus StackOverflow Dokumentationen" gekennzeichnet. +- Für Sammlungen oder neu zusammengestellte Werke, benötigt der "Urheber" eventuell eine Beschreibung. Bücher von "GoalKicker" werden z. B. als "`Zusammengestellt aus StackOverflow Dokumentationen`" (auf englisch: "`Compiled from StackOverflow documentation`") gekennzeichnet. + ##### Plattformen und Zugriffshinweise -- Kurse. Insbesondere bei unseren Kurslisten spielt die Plattform eine wichtige Rolle in der Beschreibung des Inhalts. Der Grund dafür ist, dass Kurs-Plattformen unterschiedliche Zugangsmodelle und Angebotscharakter haben. Obwohl wir keine Bücher aufnehmen, die eine Registrierung erfordern, können viele Kurs-Plattformen ohne irgendeine Art der Registrierung nicht funktionieren. Beispiele für Kurs-Plattformen sind Coursera, EdX, Udacity und Udemy. Wenn ein Kurs von einer bestimmten Plattform abhängt, sollte der Name der Plattform in Klammern angehängt werden. -- YouTube. Wir haben viele Kurse in Form von YouTube Wiedergabelisten. Wir führen Youtube nicht als Plattform auf, sondern versuchen den Urheber des Kurses zu nennen, der oftmals eine Unter-Plattform darstellt. -- YouTube Videos. Wir verlinken normalerweise keine einzelnen YouTube Videos. Ausnahmen bilden Videos von mehr als einer Stunde Länge, die wie ein Kurs oder Tutorial strukturiert sind. -- Leanpub. Leanpub beherbergt Bücher mit einer Vielzahl von Zugangsmodellen. Manchmal kann ein Buch ohne Registrierung gelesen werden; in anderen Fällen wird ein Leanpub Konto für einen kostenfreien Zugang benötigt. Aufgrund der Qualität der Bücher und der unterschiedlichen und fließenden Zugangsmodelle erlauben wir die Aufnahme letzterer, wenn sie mit dem Zugriffshinweis *(Leanpub Konto oder gültige E-Mail angefordert)* versehen sind. +- Kurse. Insbesondere bei unseren Kurslisten spielt die Plattform eine wichtige Rolle in der Beschreibung des Inhalts. Der Grund dafür ist, dass Kurs-Plattformen unterschiedliche Zugangsmodelle und Angebotscharakter haben. Obwohl wir keine Bücher aufnehmen, die eine Registrierung erfordern, können viele Kurs-Plattformen ohne irgendeine Art der Registrierung nicht funktionieren. Beispiele für Kurs-Plattformen sind Coursera, EdX, Udacity und Udemy. Wenn ein Kurs von einer bestimmten Plattform abhängt, sollte der Name der Plattform in Klammern angehängt werden. +- YouTube. Wir haben viele Kurse in Form von YouTube Wiedergabelisten. Wir führen YouTube nicht als Plattform auf, sondern versuchen den Urheber des Kurses zu nennen, der oftmals eine Unter-Plattform darstellt. +- YouTube Videos. Wir verlinken normalerweise keine einzelnen YouTube Videos. Ausnahmen bilden Videos von mehr als einer Stunde Länge, die wie ein Kurs oder Tutorial strukturiert sind. +- Leanpub. Leanpub beherbergt Bücher mit einer Vielzahl von Zugangsmodellen. Manchmal kann ein Buch ohne Registrierung gelesen werden; in anderen Fällen wird ein Leanpub Konto für einen kostenfreien Zugang benötigt. Aufgrund der Qualität der Bücher und der unterschiedlichen und fließenden Zugangsmodelle erlauben wir die Aufnahme letzterer, wenn sie mit dem Zugriffshinweis `*(Leanpub Konto oder gültige E-Mail angefordert)*` versehen sind. + #### Genre -Die wichtigste Regel zur korrekten Zuordnung von Inhalten in Listen ist zu schauen, wie die Ressource sich selbst beschreibt. Wenn sie sich als Buch bezeichnet, dann ist sie vielleicht ein Buch. +Die wichtigste Regel zur korrekten Zuordnung von Inhalten in Listen ist zu schauen, wie die Ressource sich selbst beschreibt. Wenn sie sich als Buch bezeichnet, dann ist sie vielleicht ein Buch. + ##### Genres, die wir nicht aufnehmen @@ -165,18 +187,19 @@ Da das Internet unermesslich ist, nehmen wir folgende Inhalte nicht in unsere Li - Blogs - Blogeinträge - Artikel -- Webseiten (außer jene, die SEHR viele Inhalte bereitstellen, die wir in unseren Listen führen.) +- Webseiten (außer jene, die SEHR viele Inhalte bereitstellen, die wir in unseren Listen führen). - Videos, die keine Kurse oder Screencasts sind. - einzelne Buchkapitel - Teaser oder Muster aus Büchern - IRC oder Telegram Kanäle - Slack Workspaces oder Mailinglisten -Unsere Listen zu Programmierwettbewerben setzen diese Verbote nicht so strikt um. Art und Umfang des Repositorys wird von der Community bestimmt; wenn Du eine Änderung oder Ausweitung der Ausrichtung vorschlagen möchtest, eröffne bitte ein Issue, um den Vorschlag zu unterbreiten. +Unsere Listen zu Programmierwettbewerben setzen diese Verbote nicht so strikt um. Art und Umfang des Repositorys wird von der Community bestimmt; wenn Du eine Änderung oder Ausweitung der Ausrichtung vorschlagen möchtest, eröffne bitte ein Issue, um den Vorschlag zu unterbreiten. + ##### Buch vs. anderes Zeug -Wir sind nicht kleinlich, was die Definition, was ein Buch ist und was nicht. Hier sind einige Eigenschaften, die darauf hinweisen, dass es sich bei einer bestimmten Ressource um ein Buch handelt: +Wir sind nicht kleinlich, was die Definition, was ein Buch ist und was nicht. Hier sind einige Eigenschaften, die darauf hinweisen, dass es sich bei einer bestimmten Ressource um ein Buch handelt: - es hat eine ISBN (International Standard Book Number) - es hat ein Inhaltsverzeichnis @@ -186,27 +209,30 @@ Wir sind nicht kleinlich, was die Definition, was ein Buch ist und was nicht. Hi - es versucht, ein Thema umfassend zu behandeln - es ist ein eigenständiges Werk -Vielen Büchern in unseren Listen fehlen diese Eigenschaften; es kann vom Kontext abhängen. +Vielen Büchern in unseren Listen fehlen diese Eigenschaften; es kann vom Kontext abhängen. + ##### Buch vs. Kurs Das ist manchmal gar nicht so leicht zu unterscheiden! -Kurse kommen oftmals mit begleitenden Lehrbüchern, die wir in unseren Bücherlisten führen würden. Kurse bieten Vorträge, Übungen, Tests, Anmerkungen oder andere Lernhilfen. Ein einzelner Vortrag oder Video allein ist kein Kurs. Eine Powerpoint-Präsentation ist kein Kurs. +Kurse kommen oftmals mit begleitenden Lehrbüchern, die wir in unseren Bücherlisten führen würden. Kurse bieten Vorträge, Übungen, Tests, Anmerkungen oder andere Lernhilfen. Ein einzelner Vortrag oder Video allein ist kein Kurs. Eine Powerpoint-Präsentation ist kein Kurs. + ##### Interaktive Tutorials vs. anderes Zeug -Wenn etwas ausgedruckt werden kann, ohne dass es seinen Nutzen verliert, ist es kein interaktives Tutorial. +Wenn etwas ausgedruckt werden kann, ohne dass es seinen Nutzen verliert, ist es kein interaktives Tutorial. + ### Automatisierung -- Die Durchsetzung der Formatierungsregeln wird über [GitHub Actions](https://github.com/features/actions) mittels [fpb-lint](https://github.com/vhf/free-programming-books-lint) sichergestellt (siehe [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Die Durchsetzung der Formatierungsregeln wird über [GitHub Actions](https://github.com/features/actions) mittels [fpb-lint](https://github.com/vhf/free-programming-books-lint) sichergestellt (siehe [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Die URLs werden über [awesome_bot](https://github.com/dkhamsing/awesome_bot) validiert. - Um die URL-Validierung auszulösen, kann ein Commit abgeschickt werden, der `check_urls=file_to_check` enthält: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-de.md + ``` - Man kann mehr als eine zu überprüfende Datei angeben, wobei die Einträge mit einem einzelnen Leerzeichen getrennt werden. -- Bei Angabe von mehr als einer Datei basiert das Ergebnis des Builds auf dem Ergebnis der letzten geprüften Datei. Du solltest Dir darüber im Klaren sein, dass dies zu gültigen Builds führen kann und daher das Build Protokoll am Ende des Pull Request durch Klick auf "Show all checks" -> "Details" genau geprüft werden sollte. +- Bei Angabe von mehr als einer Datei basiert das Ergebnis des Builds auf dem Ergebnis der letzten geprüften Datei. Du solltest Dir darüber im Klaren sein, dass dies zu gültigen Builds führen kann und daher das Build Protokoll am Ende des Pull Request durch Klick auf "Show all checks" -> "Details" genau geprüft werden sollte. diff --git a/docs/CONTRIBUTING-el.md b/docs/CONTRIBUTING-el.md index 449031417be66..6f77de19e0306 100644 --- a/docs/CONTRIBUTING-el.md +++ b/docs/CONTRIBUTING-el.md @@ -1,49 +1,51 @@ *[Διαβάστε το σε διαφορετικές γλώσσες](../README.md#translations)* - + ## Συμφωνία Άδειας Χρήσης Συνεισφερόντων -Συνεισφέροντας συμφωνείτε με την [ΑΔΕΙΑ](../LICENSE) αυτού του αποθετηρίου. ([translations](../README.md#translations)) +Συνεισφέροντας συμφωνείτε με την [ΑΔΕΙΑ](../LICENSE) αυτού του αποθετηρίου. - + ## Κώδικας Δεοντολογίας Συνεισφερόντων -Συνεισφέροντας συμφωνείτε να σέβεστε τον [Κώδικα Δεοντολογίας](CODE_OF_CONDUCT-el.md) αυτού του αποθετηρίου. +Συνεισφέροντας συμφωνείτε να σέβεστε τον [Κώδικα Δεοντολογίας](CODE_OF_CONDUCT-el.md) αυτού του αποθετηρίου. ([translations](../README.md#translations)) - + ## Με λίγα λόγια 1. "Ένας σύνδεσμος για να κατεβάσω εύκολα ένα βιβλίο" δεν είναι πάντα ένας σύνδεσμος για *δωρεάν* βιβλίο. Παρακαλούμε να συνεισφέρετε μόνο δωρεάν περιεχόμενο. Να σιγουρεύετε ότι είναι δωρεάν. Δεν δεχόμαστε συνδέσμους για σελίδες που *απαιτούν* λειτουργικές ηλεκτρονικές διευθύνσεις για να αποκτηθούν βιβλία, αλλά είναι ευπρόσδεκτες καταχωρήσεις που τις ζητούν προαιρετικά. + 2. Δεν χρειάζεται να γνωρίζετε Git: αν βρήκατε κάτι ενδιαφέρον που *δεν βρίσκεται ήδη σε αυτό το αποθετήριο*, παρακαλώ ανοίξτε ένα [Issue](https://github.com/EbookFoundation/free-programming-books/issues) με τις προτάσεις σας για συνδέσμους. - Αν γνωρίζετε Git, παρακαλούμε να κάνετε Fork αυτό το αποθετήριο και να στέλνετε Pull Requests (PR). + 3. Έχουμε 5 τύπους λιστών. Επιλέξτε την κατάλληλη: - *Βιβλία* : PDF, HTML, ePub, ένας ιστότοπος που βασίζεται στο gitbook.io, ένα αποθετήριο Git, κλπ. - *Μαθήματα* : Ένα μάθημα είναι εκπαιδευτικό υλικό που δεν είναι βιβλίο. [Αυτό είναι ένα μάθημα](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Διαδραστικά σεμινάρια* : Μια διαδραστική ιστοσελίδα που επιτρέπει στον χρήστη να γράψει κώδικα ή εντολές και αξιολογεί τα αποτελέσματα (με το "αξιολογεί" δεν εννοούμε "βαθμολογεί"). π.χ. [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Διαδραστικά σεμινάρια* : Μια διαδραστική ιστοσελίδα που επιτρέπει στον χρήστη να γράψει κώδικα ή εντολές και αξιολογεί τα αποτελέσματα (με το "αξιολογεί" δεν εννοούμε "βαθμολογεί"). π.χ. [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts και Screencasts*: Podcasts και screencasts. - *Προβλήματα και Ανταγωνιστικός Προγραμματισμός*: Ένας ιστότοπος ή ένα λογισμικό που σου επιτρέπει να αξιολογήσεις τις προγραμματιστικές σου ικανότητες λύνοντας απλά ή περίπλοκα προβλήματα, με ή χωρίς επιθεώρηση του κώδικα, συγκρίνοντας ή όχι τα αποτελέσματα με άλλους χρήστες. 4. Σιγουρευτείτε ότι ακολουθείτε τις [παρακάτω κατευθυντήριες γραμμές](#guidelines) και σέβεστε τη [μορφοποίηση Markdown](#formatting) των αρχείων. -5. Το GitHub Actions τρέχει δοκιμές για να ελέγξει ότι οι λίστες σας είναι σε αλφαβητική σειρά και τηρούνται οι κανόνες μορφοποίησης. Να θυμάστε να ελέγχετε ότι οι αλλαγές σας περνούν τις δοκιμές. +5. Το GitHub Actions τρέχει δοκιμές για να ελέγξει ότι **οι λίστες σας είναι σε αλφαβητική σειρά** και **τηρούνται οι κανόνες μορφοποίησης**. **Να θυμάστε να** ελέγχετε ότι οι αλλαγές σας περνούν τις δοκιμές. - + ### Κατευθυντήριες Γραμμές - σιγουρευτείτε ότι το βιβλίο είναι δωρεάν. Επανελέγξτε αν χρειάζεται. Βοηθάει τους διαχειριστές αν σχολιάζετε στο PR τον λόγο που πιστεύετε ότι αυτό το βιβλίο είναι δωρεάν. - δεν δεχόμαστε αρχεία που φιλοξενούνται στα Google Drive, Dropbox, Mega, Scribd, Issuu και άλλες παρόμοιες πλατφόρμες ανεβάσματος αρχείων - εισάγετε τους συνδέσμους σας σε αλφαβητική σειρά. Αν βάλετε έναν σύνδεσμο σε λάθος θέση, παρακαλούμε διορθώστε το και υποβάλλετε νέο PR - χρησιμοποιήστε έναν σύνδεσμο με την πιο έγκυρη πηγή (που σημαίνει ότι η ιστοσελίδα του συγγραφέα είναι καλύτερη από τη σελίδα του εκδότη, η οποία είναι καλύτερη από μια τρίτη ιστοσελίδα) - + δεν επιτρέπονται υπηρεσίες φιλοξενίας αρχείων (αυτό περιλαμβάνει (αλλά δεν περιορίζεται στους) συνδέσμους από Dropbox και Google Drive) + - δεν επιτρέπονται υπηρεσίες φιλοξενίας αρχείων (αυτό περιλαμβάνει (αλλά δεν περιορίζεται στους) συνδέσμους από Dropbox και Google Drive) - να προτιμάτε ένα σύνδεσμο `https` από έναν `http` -- αρκεί να είναι στο ίδιο domain και να εξυπηρετούν τον ίδιο περιεχόμενο - στα root domains, αφαιρέστε την τελευταία κάθετο: `http://example.com` αντί για `http://example.com/` - να προτιμάτε πάντα τους μικρότερους συνδέσμους: `http://example.com/dir/` είναι καλύτερα από `http://example.com/dir/index.html` - + δεν επιτρέπονται περικομμένοι σύνδεσμοι (URL shortener) + - δεν επιτρέπονται περικομμένοι σύνδεσμοι (URL shortener) - να προτιμάτε συνήθως τους "τρέχοντες" συνδέσμους από τους συνδέσμους "εκδόσεων": `http://example.com/dir/book/current/` είναι καλύτερα από `http://example.com/dir/book/v1.0.0/index.html` - αν ένας σύνδεσμος έχει ληγμένο πιστοποιητικό/αυτοϋπογεγραμμένο πιστοποιητικό/κάποια θέμα άλλου είδους με SSL: 1. *αντικαταστήστε το* με το `http` αντίστοιχό του αν είναι δυνατό (επειδή το να γίνονται αποδεκτές εξαιρέσεις μπορεί να είναι περίπλοκο σε φορητές συσκευές). @@ -51,17 +53,17 @@ 3. *αφαιρέστε το* σε κάθε άλλη περίπτωση - αν ένας σύνδεσμος υπάρχει σε διαφορετικά format, προσθέστε διαφορετικό σύνδεσμο με μια σημείωση για κάθε format - αν κάποιο υλικό υπάρχει σε διαφορετικά μέρη στο Internet - + χρησιμοποιείστε τον σύνδεσμο με την πιο έγκυρη πηγή (που σημαίνει ότι η ιστοσελίδα του συγγραφέα είναι καλύτερη από τη σελίδα του εκδότη, η οποία είναι καλύτερη από μια τρίτη ιστοσελίδα) - + αν οδηγούν σε διαφορετικές εκδόσεις, και θεωρείτε πως αυτές οι εκδόσεις είναι αρκετά διαφορετικές ώστε να έχει αξία η διατήρησή τους, προσθέστε διαφορετικό σύνδεσμο με μια σημείωση για κάθε έκδοση (δείτε το [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) για να συνεισφέρετε στη συζήτηση για τη μορφοποίηση) + - χρησιμοποιείστε τον σύνδεσμο με την πιο έγκυρη πηγή (που σημαίνει ότι η ιστοσελίδα του συγγραφέα είναι καλύτερη από τη σελίδα του εκδότη, η οποία είναι καλύτερη από μια τρίτη ιστοσελίδα) + - αν οδηγούν σε διαφορετικές εκδόσεις, και θεωρείτε πως αυτές οι εκδόσεις είναι αρκετά διαφορετικές ώστε να έχει αξία η διατήρησή τους, προσθέστε διαφορετικό σύνδεσμο με μια σημείωση για κάθε έκδοση (δείτε το [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) για να συνεισφέρετε στη συζήτηση για τη μορφοποίηση) - προτιμήστε ατομικά commits (ένα commit ανά προσθήκη/διαγραφή/τροποποίηση) αντί για μεγαλύτερα commits. Δεν υπάρχει ανάγκη να συνενώνετε τα commits πριν υποβάλλετε ένα PR. (Δεν θα επιβάλλουμε ποτέ αυτόν τον κανόνα εφ' όσον είναι απλά ζήτημα διευκόλυνσης για τους διατηρητές) - αν το βιβλίο είναι παλιό, περιλαμβάνετε την ημερομηνία δημοσίευσης με τον τίτλο -- συμπεριλαμβάνετε το όνομα ή τα ονόματα του συγγραφέα όπου είναι απαραίτητο. Μπορείτε να μικρύνετε τις λίστες συγγραφέων με το "et al." -- αν το βιβλίο δεν έχει τελειώσει, και βρίσκεται ακόμα υπό συγγραφή, προσθέστε τη σημείωση "σε εξέλιξη", όπως περιγράφεται [παρακάτω.](#in_process) -- αν το υλικό έχει ανακτηθεί χρησιμοποιώντας το Internet's Archive Wayback Machine (ή παρόμοια), προσθέτε την ένδειξη "αρχείοθετημένο" (στα αγγλικά: "archived"), όπως περιγράφεται [παρακάτω](#archived). Οι καλύτερες εκδοχές για να χρησιμοποιήσετε είναι οι πρόσφατες και πλήρεις. -- αν ζητείται διεύθυνση ηλεκτρονικού ταχυδρομείου ή δημιουργία λογαριασμού πριν την ενεργοποίηση της λήψης, προσθέστε κατάλληλες σημειώσεις ανάλογα με τη γλώσσα σε παρένθεση, π.χ. `(διεύθυνση email *ζητείται*, δεν είναι απαραίτητη)` +- συμπεριλαμβάνετε το όνομα ή τα ονόματα του συγγραφέα όπου είναι απαραίτητο. Μπορείτε να μικρύνετε τις λίστες συγγραφέων με το "`et al.`". +- αν το βιβλίο δεν έχει τελειώσει, και βρίσκεται ακόμα υπό συγγραφή, προσθέστε τη σημείωση "`in process`", όπως περιγράφεται [παρακάτω](#in_process). +- αν το υλικό έχει ανακτηθεί χρησιμοποιώντας το [*Internet Archive's Wayback Machine*](https://web.archive.org) (ή παρόμοια), προσθέτε την ένδειξη "`αρχείοθετημένο`" (στα αγγλικά: "`archived`"), όπως περιγράφεται [παρακάτω](#archived). Οι καλύτερες εκδοχές για να χρησιμοποιήσετε είναι οι πρόσφατες και πλήρεις. +- αν ζητείται διεύθυνση ηλεκτρονικού ταχυδρομείου ή δημιουργία λογαριασμού πριν την ενεργοποίηση της λήψης, προσθέστε κατάλληλες σημειώσεις ανάλογα με τη γλώσσα σε παρένθεση, π.χ. `(διεύθυνση email *ζητείται*, δεν είναι απαραίτητη)`. - + ### Μορφοποίηση - Όλες οι λίστες είναι αρχεία `.md`. Προσπαθήστε να μάθετε τη σύνταξη του [Markdown](https://guides.github.com/features/mastering-markdown/). Είναι απλή! @@ -69,6 +71,7 @@ - Οι ενότητες χρησιμοποιούν επικεφαλίδες επιπέδου 3 (`###`), και οι υποενότητες είναι επικεφαλίδες επιπέδου 4 (`####`). Η ιδέα είναι να έχουμε: + - `2` κενές γραμμές μεταξύ τελευταίου συνδέσμου και νέας ενότητας - `1` κενή γραμμή μεταξύ επικεφαλίδας & πρώτου συνδέσμου της ενότητάς του - `0` κενές γραμμές μεταξύ δύο συνδέσμων @@ -76,93 +79,99 @@ Παράδειγμα: - [...] - * [Ένα Φοβερό Βιβλίο](http://example.com/example.html) - (κενή γραμμή) - (κενή γραμμή) - ### Παράδειγμα - (κενή γραμμή) - * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) - * [Κάποιο Άλλο Βιβλίο](http://example.com/other.html) +```text +[..]. +* [Ένα Φοβερό Βιβλίο](http://example.com/example.html) + (κενή γραμμή) + (κενή γραμμή) +### Παράδειγμα + (κενή γραμμή) +* [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) +* [Κάποιο Άλλο Βιβλίο](http://example.com/other.html) +``` - Μη βάζετε κενό μεταξύ `]` και `(`: -``` -ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο] (http://example.com/book.html) -ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) -``` + ```text + ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο] (http://example.com/book.html) + ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) + ``` - Αν συμπεριλαμβάνετε συγγραφέα, χρησιμοποιήστε ` - ` (μια παύλα που περιβάλλεται από κενά): -``` -ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)- John Doe -ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) - John Doe -``` + ```text + ΚΑΚΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html)- John Doe + ΚΑΛΟ: * [Άλλο Φοβερό Βιβλίο](http://example.com/book.html) - John Doe + ``` - Εισάγετε ένα κενό μεταξύ του συνδέσμου και του format του: -``` -ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)(PDF) -ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) (PDF) -``` + ```text + ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)(PDF) + ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) (PDF) + ``` - Ο συγγραφέας μπαίνει πριν το format -``` -ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)- (PDF) Jane Roe -ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf)- (PDF) Jane Roe + ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Πολλαπλά formats: -``` -ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/)- John Doe (HTML) -ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://downloads.example.org/book.html)- John Doe (download site) -ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/)- John Doe (HTML) + ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://downloads.example.org/book.html)- John Doe (download site) + ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Συμπεριλαμβάνετε χρονιά δημοσιεύσης στον τίτλο για παλαιότερα βιβλία: -``` -ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.html) - Jane Roe - 1970 -ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο (1970)](https://example.org/book.html) - Jane Roe -``` - -- Βιβλία σε εξέλιξη: + ```text + ΚΑΚΟ: * [Ένα Πολύ Φοβερό Βιβλίο](https://example.org/book.html) - Jane Roe - 1970 + ΚΑΛΟ: * [Ένα Πολύ Φοβερό Βιβλίο (1970)](https://example.org/book.html) - Jane Roe + ``` -``` -ΚΑΛΟ: * [Θα Είναι Σύντομα Ένα Φοβερό Βιβλίο](http://example.com/book2.html) - John Doe (HTML) (:construction: *σε εξέλιξη*) -``` - -- Αρχειοθετημένοι σύνδεσμοι: +- Βιβλία σε εξέλιξη: -``` -ΚΑΛΟ: * [Ένα Ενδιαφέρον Way-backed Βιβλίο](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: αρχειοθετημένο)* -``` + ```text + ΚΑΛΟ: * [Θα Είναι Σύντομα Ένα Φοβερό Βιβλίο](http://example.com/book2.html) - John Doe (HTML) (:construction: *σε εξέλιξη*) + ``` +- Αρχειοθετημένοι σύνδεσμοι: - + ```text + ΚΑΛΟ: * [Ένα Ενδιαφέρον Way-backed Βιβλίο](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: αρχειοθετημένο)* + ``` + + + ### Σημειώσεις Αν και τα βασικά είναι σχετικά απλά, υπάρχει μεγάλη ποικιλία στο υλικό που παρουσιάζουμε. Ορίστε μερικές σημειώσεις για το πως να αντιμετωπίσετε αυτή την ποικιλία + #### Metadata Οι λίστες μας παρέχουν ένα ελάχιστο σύνολο από metadata: τίτλους, URLs, δημιουργούς, πλατφόρμες, και σημειώσεις πρόσβασης + #### Τίτλοι - Όχι δικοί σας τίτλοι. Προσπαθούμε να πάρουμε τους τίτλους από τις ίδιες τις πηγές· οι συνεισφέροντες επιβάλλεται να μη εφευρίσκουν τίτλους ή να τους χρησιμοποιούν εκδοτικά αν αυτό μπορεί να αποφευχθεί. Μια εξαίρεση είναι για παλαιότερα έργα· αν είναι παρουσιάζουν κυρίως ιστορικό ενδιαφέρον, το έτος στην παρένθεση προσαρτημένο με τον τίτλο βοηθά τους χρήστες να γνωρίζουν αν τους ενδιαφέρει. - Όχι τίτλοι αποκλειστικά σε ΚΕΦΑΛΑΙΑ. Η συνήθης κεφαλαιοποίηση τίτλων (title case) είναι κατάλληλη, αλλά όταν υπάρχουν αμφιβολίες χρησιμοποιήστε την κεφαλαιοποίηση της πηγής + #### URLs - Δεν επιτρέπουμε περικομμένα URLs. - Κωδικοί ανίχνευσης πρέπει να αφαιρεθούν από το URL. - Τα διεθνή URLs πρέπει να είναι escaped. Οι browsers τυπικά τα μετατρέπουν σε Unicode, αλλά χρησιμοποιήστε αντιγραφή και επικόλληση, παρακαλούμε. -- Ασφαλή (https) URLs προτιμώνται πάντα αντί για μη ασφαλή (http) urls για τα οποία έχει υλοποιηθεί https. +- Ασφαλή (`https`) URLs προτιμώνται πάντα αντί για μη ασφαλή (`http`) urls για τα οποία έχει υλοποιηθεί HTTPS. - Δεν μας αρέσουν URLs που οδηγούν σε ιστοσελίδες που δεν φιλοξενούν το υλικό που αναφέρεται, αλλά αντ' αυτού οδηγούν αλλού. + #### Δημιουργοί - Θέλουμε να αναφέρονται τα ονόματα των δημιουργών δωρεάν υλικού όπου κρίνεται κατάλληλο, συμπεριλαμβανομένων των μεταφραστών! @@ -170,18 +179,21 @@ - Δεν επιτρέπουμε συνδέσμους για Δημιουργούς. - Για συλλεγμένα ή επεξεργασμένα έργα, ο "δημιουργός" ίσως χρειάζεται περιγραφή. Για παράδειγμα, τα βιβλία από το "GoalKicker" ή "RIP Tutorial" αναφέρονται ως "`Συντάχθηκαν από documentation του StackOverflow`" (στα αγγλικά: "`Compiled from StackOverflow documentation`"). + #### Πλατφόρμες και Σημειώσεις Πρόσβασης - Μαθήματα. Ειδικά για τις λίστες μαθημάτων μας, η πλατφόρμα είναι ένα σημαντικό κομμάτι της περιγραφής του υλικού. Αυτό επειδή οι πλατφόρμες με μαθήματα έχουν διαφορετική προσβασιμότητα και μοντέλα πρόσβασης. Ενώ συνήθως δεν θα προσθέσουμε ένα βιβλίο που απαιτεί εγγραφή, πολλές πλατφόρμες μαθημάτων έχουν χαρακτηριστικά που δεν θα δουλέψουν χωρίς κάποιο τύπο λογαριασμού. Παραδείγματα πλατφορμών μαθημάτων περιλαμβάνουν τα Coursera, EdX, Udacity και Udemy. Όταν ένα μάθημα εξαρτάται από την πλατφόρμα, το όνομα της πλατφόρμας θα πρέπει να αναφέρεται σε παρένθεση. - YouTube. Έχουμε πολλά μαθήματα που αποτελούνται από playlists στο YouTube. Δεν παραθέτουμε το YouTube σαν πλατφόρμα, προσπαθούμε να αναφέρουμε τον δημιουργό στο YouTube, που είναι συνήθως υπό-πλατφόρμα. - Βίντεο στο YouTube. Συνήθως δεν δεχόμαστε σε ατομικά βίντεο του YouTube εκτός αν είναι περισσότερο από μια ώρα και έχουν δομή σαν μάθημα ή σεμινάριο. -- Leanpub. Το Leanpub φιλοξενεί βιβλία με διαφορετικά μοντέλα πρόσβασης. Κάποιες φορές ένα βιβλίο μπορεί να διαβαστεί εγγραφή· κάποιες φορές ένα βιβλίο απαιτεί λογαριασμό στο Leanpub για δωρεάν πρόσβαση. Δεδομένης της ποιότητας των βιβλίων και του μίγματος και της ρευστότητας των μοντέλων πρόσβασης του Leanpub, επιτρέπουμε την παράθεση του τελευταίου με τη σημείωση πρόσβασης `*(Ζητείται λογαριασμός Leanpub ή έγκυρο email)*` +- Leanpub. Το Leanpub φιλοξενεί βιβλία με διαφορετικά μοντέλα πρόσβασης. Κάποιες φορές ένα βιβλίο μπορεί να διαβαστεί εγγραφή· κάποιες φορές ένα βιβλίο απαιτεί λογαριασμό στο Leanpub για δωρεάν πρόσβαση. Δεδομένης της ποιότητας των βιβλίων και του μίγματος και της ρευστότητας των μοντέλων πρόσβασης του Leanpub, επιτρέπουμε την παράθεση του τελευταίου με τη σημείωση πρόσβασης `*(Ζητείται λογαριασμός Leanpub ή έγκυρο email)*`. + - + #### Είδη Ο πρώτος κανόνας στην απόφαση για το σε ποια λίστα ανήκει το υλικό είναι να δείτε πώς περιγράφει τον εαυτό του. Αν αυτοαποκαλείται βιβλίο, τότε ίσως είναι βιβλίο. + #### Είδη που δεν παραθέτουμε Επειδή το Internet είναι μεγάλο, δεν περιέχουμε στις λίστες μας: @@ -189,7 +201,7 @@ - blogs - blog posts - άρθρα -- ιστοσελίδες (εκτός από αυτές που φιλοξενούν ΠΟΛΛΑ από τα αντικείμενα που παραθέτουμε.) +- ιστοσελίδες (εκτός από αυτές που φιλοξενούν ΠΟΛΛΑ από τα αντικείμενα που παραθέτουμε). - βίντεο που δεν είναι μαθήματα ή screencasts. - κεφάλαια βιβλίων - δείγματα από βιβλία @@ -226,16 +238,16 @@ Αν μπορείτε να το τυπώσετε και να διατηρήσετε την ουσία του, δεν είναι Διαδραστικό Σεμινάριο. - + ### Αυτοματισμός -- Η επιβολή των κανόνων μορφοποίησης αυτοματοποιείται από το [GitHub Actions](https://github.com/features/actions) χρησιμοποιώντας [fpb-lint](https://github.com/vhf/free-programming-books-lint) (βλ. [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Η επιβολή των κανόνων μορφοποίησης αυτοματοποιείται από το [GitHub Actions](https://github.com/features/actions) χρησιμοποιώντας [fpb-lint](https://github.com/vhf/free-programming-books-lint) (βλ. [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Η επικύρωση των URL χρησιμοποιεί το [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Για να ενεργοποιήσετε την επικύρωση του URL, κάντε push ένα commit που περιέχει ένα μήνυμα στο οποίο υπάρχει το `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-el.md + ``` - Μπορείτε να προσδιορίσετε πάνω από ένα αρχείο για έλεγχο, χρησιμοποιώντας ένα κενό για να ξεχωρίσετε κάθε καταχώρηση. -- Αν προσδιορίσετε πάνω από ένα αρχείο, τα αποτελέσματα του build βασίζονται στα αποτελέσματα του τελευταίου αρχείου που ελέγχθηκε. Θα πρέπει να γνωρίζετε ότι ενδέχεται να πάρετε επικυρωμένα builds εξαιτίας αυτού οπότε να είστε σίγουροι ότι επιβλέπετε το αρχείο του build στο τέλος του pull request πατώντας στο "Show all checks" -> "Details". +- Αν προσδιορίσετε πάνω από ένα αρχείο, τα αποτελέσματα του build βασίζονται στα αποτελέσματα του τελευταίου αρχείου που ελέγχθηκε. Θα πρέπει να γνωρίζετε ότι ενδέχεται να πάρετε επικυρωμένα builds εξαιτίας αυτού οπότε να είστε σίγουροι ότι επιβλέπετε το αρχείο του build στο τέλος του Pull Request πατώντας στο "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-es.md b/docs/CONTRIBUTING-es.md index fb505f1845089..e882c71e96494 100644 --- a/docs/CONTRIBUTING-es.md +++ b/docs/CONTRIBUTING-es.md @@ -1,23 +1,26 @@ *[Lea esto en otros idiomas][translations-list-link]* - + + ## Acuerdo de Licencia Al contribuir, acepta la [LICENCIA][license] de este repositorio. - + ## Código de Conducta como Colaborador Al contribuir, acepta respetar el [Código de Conducta][coc] ([traducciones / otros idiomas][translations-list-link]) presente en el repositorio. - + ## Breve resumen 1. "Un enlace para descargar fácilmente un libro" no siempre es un enlace a un libro *gratuito*. Por favor, contribuya solo con contenido gratuito. Asegúrese de que se ofrezca gratis. No se aceptan enlaces a páginas que *requieran* de direcciones de correo electrónico para la obtención de libros, pero sí damos la bienvenida a aquellos listados que así se soliciten. + 2. No es necesario conocer Git: si encontró algo de interés que *no esté ya en este repositorio*, tenga el gusto de abrir una [Issue][issues] con su propuesta de enlaces. - Si ya maneja Git, haga un Fork del repositorio y envíe su contribución mediante Pull Request (PR). + 3. Dispone de 5 categorías. Seleccione aquel listado que crea conveniente según: - *Libros* : PDF, HTML, ePub, un recurso alojado en gitbook.io, un repositorio Git, etc. @@ -28,39 +31,39 @@ Al contribuir, acepta respetar el [Código de Conducta][coc] ([traducciones / ot 4. Asegúrese de seguir la [guía de pautas que mostramos a continuación][guidelines] así como de respetar el [formato Markdown][formatting] de los ficheros. -5. GitHub Actions ejecutará pruebas para asegurarse de que las listas esten ordenadas alfabéticamente y de que se siga dicha normalización de formateo. Asegúrese de verificar que sus cambios pasen todas estas comprobaciones de calidad. +5. GitHub Actions ejecutará pruebas para asegurarse de que **las listas esten ordenadas alfabéticamente** y de que se **siga dicha normalización de formateo**. **Asegúrese** de verificar que sus cambios pasen todas estas comprobaciones de calidad. - + ### Pautas -- Revise si el libro es gratuito. Hágalo las veces que sean necesarias. Ayude a los administradores comentando en las Pull Request por qué cree que el libro se ofrece gratis o es valioso. +- Revise si el libro es gratuito. Hágalo las veces que sean necesarias. Ayude a los administradores comentando en las PR por qué cree que el libro se ofrece gratis o es valioso. - No se aceptan ficheros alojados en Google Drive, Dropbox, Mega, Scribd, Issuu u otras plataformas de almacenamiento y/o descarga similares. - Inserte los enlaces ordenados alfabéticamente. Si se encuentra por casualidad con un enlace fuera de sitio, por favor ordénelo y envíe la correspondiente PR para poder arreglarlo. - Use el enlace que apunte a la fuente más fidedigna. Esto es, el sitio web del autor es mejor que el del editor y éste a su vez mejor que uno de terceros. - + No use servicios de almacenamiento en la nube. Esto incluye, aunque sin limitar, enlaces a Dropbox y Google Drive. + - No use servicios de almacenamiento en la nube. Esto incluye, aunque sin limitar, enlaces a Dropbox y Google Drive. - Es siempre preferible el uso de enlaces con protocolo `https` en vez de `http` si ambos se refieren al mismo dominio y sirven el mismo contenido. - En los dominios raíz, elimine la barra inclinada del final: `http://example.com` en lugar de `http://example.com/`. - Utilice preferentemente la forma corta de los hipervínculos: `http://example.com/dir/` es mejor que `http://example.com/dir/index.html`. - + No se admiten acortadores de enlaces URL. + - No se admiten acortadores de enlaces URL. - Por lo general, se prefiere el enlace "actual" sobre el de "versión": `http://example.com/dir/book/current/` es más asequible que `http://example.com/dir/book/v1.0.0/index.html`. - Si en un enlace se encuentra con algún problema de certificados, ya sea caducado, autofirmado o de cualquier otro tipo: - 1. *Reemplácelo* con su análogo `http` si fuera posible (porque aceptar excepciones puede ser complicado en dispositivos móviles). - 2. *Manténgalo* si no existe versión `http` pero el enlace aún es accesible a través de `https` agregando una excepción al navegador o ignorando la advertencia. - 3. *Elimínelo* en cualquier otro caso. + 1. *Reemplácelo* con su análogo `http` si fuera posible (porque aceptar excepciones puede ser complicado en dispositivos móviles). + 2. *Manténgalo* si no existe versión `http` pero el enlace aún es accesible a través de `https` agregando una excepción al navegador o ignorando la advertencia. + 3. *Elimínelo* en cualquier otro caso. - Si existe un mismo enlace con varios formatos, anexe enlaces aparte con una nota sobre cada formato. - Si un recurso existe en diferentes lugares de Internet: - + Use aquella fuente más fidedigna (lo que significa que el sitio web del propio autor es más asequible que el sitio web del editor y a su vez éste es mejor que una fuente de terceros). - + Si apuntan a diferentes ediciones y considera que estas ediciones son lo suficientemente dispares como para que valga la pena conservarlas, agregue por separado un nuevo enlace haciendo alusión a cada edición. Diríjase al [Issue \#2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) si desea contribuir en la discusión acerca del formateo que deben seguir dichos registros. + - Use aquella fuente más fidedigna (lo que significa que el sitio web del propio autor es más asequible que el sitio web del editor y a su vez éste es mejor que una fuente de terceros). + - Si apuntan a diferentes ediciones y considera que estas ediciones son lo suficientemente dispares como para que valga la pena conservarlas, agregue por separado un nuevo enlace haciendo alusión a cada edición. Diríjase al [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) si desea contribuir en la discusión acerca del formateo que deben seguir dichos registros. - Es preferible realizar commits atómicos (un commit por cada adición/eliminación/modificación) frente a unos con mayor calado. No es necesario realizar un squash de todos ellos antes de enviar una PR. (Nunca aplicaremos esta regla, ya que solamente es una cuestión de conveniencia para quien mantiene el proyecto). - Si se trata de un libro más antiguo, incluya su fecha de publicación dentro del título. - Incluya el nombre o nombres de autor/es cuando corresponda. Puede valerse de "`et al.`" para acortar esa enumeración de autores. -- Si el libro no está terminado y aún se está trabajando en él, agregue la anotación de "`en proceso`", tal y como se describe [a continuación][in_process]. +- Si el libro no está terminado y aún se está trabajando en él, agregue la anotación de "`in process`", tal y como se describe [a continuación][in_process]. - En el caso de que decida recuperar un recurso usando servicios como [*Internet Archive's Wayback Machine*](https://web.archive.org), anexe la anotación "`archived`" (en consonancia con el idioma) tal y como se describe [a continuación][archived]. Use como mejor versión aquella que sea la más reciente y completa. - Si se solicita una dirección de correo electrónico o configuración de cuenta antes de habilitar la descarga, agregue entre paréntesis dichas notas y en consonancia con el idioma. Por ejemplo: `(*se solicita* email, no requerido...)`. - + ### Formato normalizado - Como podrá observar, los listados tienen `.md` como extensión de fichero. Intente aprender la sintaxis [Markdown][markdown_guide]. ¡Es bastante simple! @@ -68,6 +71,7 @@ Al contribuir, acepta respetar el [Código de Conducta][coc] ([traducciones / ot - Las secciones utilizan encabezados de nivel 3 (`###`) y las subsecciones de nivel 4 (`####`). La idea es tener: + - `2` líneas vacías entre el último enlace de una sección y el título de la siguiente sección. - `1` línea vacía entre la cabecera y el primer enlace de una determinada sección. - `0` líneas en blanco entre los distintos enlaces. @@ -75,99 +79,103 @@ La idea es tener: Ejemplo: - [...] - * [Un libro increíble](http://example.com/example.html) - (línea en blanco) - (línea en blanco) - ### Sección de ejemplo - (línea en blanco) - * [Otro libro fascinante](http://example.com/book.html) - * [Otro libro más](http://example.com/other.html) +```text +[...] +* [Un libro increíble](http://example.com/example.html) + (línea en blanco) + (línea en blanco) +### Sección de ejemplo + (línea en blanco) +* [Otro libro fascinante](http://example.com/book.html) +* [Otro libro más](http://example.com/other.html) +``` - Omita los espacios entre `]` y `(`: - ``` - INCORRECTO : * [Otro libro fascinante] (http://example.com/book.html) - CORRECTO : * [Otro libro fascinante](http://example.com/book.html) - ``` + ```text + INCORRECTO: * [Otro libro fascinante] (http://example.com/book.html) + CORRECTO : * [Otro libro fascinante](http://example.com/book.html) + ``` - Si en el registro decide incluir al autor, emplee ` - ` (un guión rodeado de espacios simples) como separador: - ``` - INCORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html)- John Doe - CORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html) - John Doe - ``` + ```text + INCORRECTO: * [Un libro sencillamente fabuloso](http://example.com/book.html)- John Doe + CORRECTO : * [Un libro sencillamente fabuloso](http://example.com/book.html) - John Doe + ``` - Ponga un solo espacio entre el enlace al contenido y su formato: - ``` - INCORRECTO : * [Un libro muy interesante](https://example.org/book.pdf)(PDF) - CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) (PDF) - ``` + ```text + INCORRECTO: * [Un libro muy interesante](https://example.org/book.pdf)(PDF) + CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) (PDF) + ``` - El autor se antepone al formato: - ``` - INCORRECTO : * [Un libro muy interesante](https://example.org/book.pdf)- (PDF) Jane Roe - CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) - Jane Roe (PDF) - ``` + ```text + INCORRECTO: * [Un libro muy interesante](https://example.org/book.pdf)- (PDF) Jane Roe + CORRECTO : * [Un libro muy interesante](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Múltiples formatos: - ``` - INCORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML) - INCORRECTO : * [Otro libro interesante](https://downloads.example.org/book.html) - John Doe (sitio de descarga) - CORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) - ``` + ```text + INCORRECTO: * [Otro libro interesante](http://example.com/) - John Doe (HTML) + INCORRECTO: * [Otro libro interesante](https://downloads.example.org/book.html) - John Doe (sitio de descarga) + CORRECTO : * [Otro libro interesante](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Incluya el año de publicación como parte del título de los libros más antiguos: - ``` - INCORRECTO : * [Un libro bastante especial](https://example.org/book.html) - Jane Roe - 1970 - CORRECTO : * [Un libro bastante especial (1970)](https://example.org/book.html) - Jane Roe - ``` + ```text + INCORRECTO: * [Un libro bastante especial](https://example.org/book.html) - Jane Roe - 1970 + CORRECTO : * [Un libro bastante especial (1970)](https://example.org/book.html) - Jane Roe + ``` - -- Libros en proceso / no acabados aún: +- Libros en proceso / no acabados aún: - ``` - CORRECTO: * [A punto de ser un libro fascinante](http://example.com/book2.html) - John Doe (HTML) (:construction: *en proceso*) - ``` + ```text + CORRECTO : * [A punto de ser un libro fascinante](http://example.com/book2.html) - John Doe (HTML) (:construction: *en proceso*) + ``` - -- Enlaces archivados: +- Enlaces archivados: - ``` - CORRECTO: * [Un recurso recuperado a partir de su línea de tiempo](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archivado)* - ``` + ```text + CORRECTO : * [Un recurso recuperado a partir de su línea de tiempo](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archivado)* + ``` - + ### Anotaciones Si bien los conceptos básicos son relativamente simples, existe una gran diversidad entre los recursos que enumeramos. Aquí hay algunas notas sobre cómo nos ocupamos de esta diversidad. - + + #### Metadatos Nuestros listados proporcionan un conjunto mínimo de metadatos: títulos, URL, autores, formato, plataformas y notas de acceso. - + + ##### Títulos - Sin títulos inventados: Intentamos tomar el texto de los propios recursos; se advierte a los colaboradores que, si puede evitarse, no inventen títulos ni los utilicen editorialmente. Una excepción es para obras más antiguas: si son principalmente de interés histórico, un año entre paréntesis adjunto al título ayuda a los usuarios a saber si estos son de interés. -- Sin títulos todo en mayúsculas: Por lo general, es apropiado tener cada primera letra de palabra en mayúsculas, pero en caso de duda, use siempre el estilo tal y como viene en la fuente original. +- Sin títulos TODO EN MAYÚSCULAS: Por lo general, es apropiado tener cada primera letra de palabra en mayúsculas, pero en caso de duda, use siempre el estilo tal y como viene en la fuente original. + - + ##### Direcciones URL - No se permiten acortadores de URLs para los enlaces. - Los parámetros de consulta o códigos referentes al seguimiento o campañas de marketing deben eliminarse de la URL. - Las URL internacionales deben escaparse. Las barras del navegador suelen representar los caracteres en Unicode, pero utilice copiar y pegar, por favor; es la forma más rápida de construir un hipervínculo válido. -- Las URL seguras (https) siempre son mejor opción frente a las no seguras (http) donde se ha implementado el protocolo de comunicación encriptado HTTPS. +- Las URL seguras (`https`) siempre son mejor opción frente a las no seguras (`http`) donde se ha implementado el protocolo de comunicación encriptado HTTPS. - No nos gustan las URL que apuntan a páginas web que no alojen el recurso mencionado, enlazando por el contrario a otra parte. - + + ##### Atribuciones - Queremos dar crédito a los creadores de recursos gratuitos cuando sea apropiado, ¡incluso traductores! @@ -175,20 +183,23 @@ Nuestros listados proporcionan un conjunto mínimo de metadatos: títulos, URL, - No permitimos enlaces directos al creador. - En el caso de recopilaciones u obras remezcladas, el "creador" puede necesitar una descripción. Por ejemplo, los libros de "GoalKicker" o "RIP Tutorial" se acreditan como "`Creado a partir de la documentación de StackOverflow`" (en inglés: "`Compiled from StackOverflow documentation`"). - + + ##### Plataformas y Notas de Acceso - Cursos. Especialmente para nuestras listas de cursos, la plataforma es una parte importante de la descripción del recurso. Esto se debe a que las plataformas de cursos tienen diferentes prestaciones y modelos de acceso. Si bien generalmente no incluimos un libro que requiere de registro previo, muchas plataformas de cursos tienen la casualidad de no funcionar sin algún tipo de cuenta. Un ejemplo de plataformas de cursos podrían ser: Coursera, EdX, Udacity y Udemy. Cuando un curso depende de una plataforma, el nombre de dicha plataforma debe aparecer entre paréntesis. -- YouTube. Tenemos muchos cursos que consisten en listas de reproducción de YouTube. No incluimos Youtube como plataforma, sino que tratamos de incluir al creador de Youtube, el cuál es a menudo una sub-plataforma en sí. +- YouTube. Tenemos muchos cursos que consisten en listas de reproducción de YouTube. No incluimos YouTube como plataforma, sino que tratamos de incluir al creador de YouTube, el cuál es a menudo una sub-plataforma en sí. - Vídeos de YouTube. Por lo general, no vinculamos a vídeos individuales de YouTube a menos que tengan más de una hora de duración y estén estructurados como un curso o un tutorial. -- LeanPub. LeanPub aloja libros con una amplia variedad de modelos de acceso. A veces, un libro se puede leer sin registrarse; en otras, un libro requiere una cuenta LeanPub para tener acceso gratuito. Dada la calidad de los libros y la mezcla y fluidez de los modelos de acceso Leanpub, damos validez a estos últimos anexando la nota de acceso: `*(cuenta Leanpub o email válido requerido)*`. +- Leanpub. Leanpub aloja libros con una amplia variedad de modelos de acceso. A veces, un libro se puede leer sin registrarse; en otras, un libro requiere una cuenta Leanpub para tener acceso gratuito. Dada la calidad de los libros y la mezcla y fluidez de los modelos de acceso Leanpub, damos validez a estos últimos anexando la nota de acceso: `*(cuenta Leanpub o email válido requerido)*`. + - + #### Géneros La primera regla para decidir en qué listado encaja un determinado recurso es ver cómo se describe a sí mismo. Si por ejemplo se retrata a sí mismo como un libro, entonces tal vez es que lo sea. - + + ##### Géneros no aceptados Ya que en Internet podemos encontrar una variedad infinita de recursos, no incluimos en nuestro registro: @@ -205,12 +216,13 @@ Ya que en Internet podemos encontrar una variedad infinita de recursos, no inclu El [listado donde incluimos sitios o software de programación competitiva][programming_playgrounds_list] no es tan restrictivo. El alcance de este repositorio es determinado por la comunidad; si desea sugerir un cambio o extender el alcance, utilice los [issues][issues] para registrar dicha sugerencia. - + + ##### Libros vs. Otro Material No somos tan quisquillosos con lo que consideramos como libro. A continuación, se muestran algunas propiedades que un recurso pueda encajar como libro: -- tiene un ISBN +- tiene un ISBN (International Standard Book Number) - tiene una Tabla de Contenidos (TOC) - se ofrece una versión para su descarga electrónica, especialmente ePub. - tiene diversas ediciones @@ -220,32 +232,34 @@ No somos tan quisquillosos con lo que consideramos como libro. A continuación, Hay muchos libros que enumeramos los cuáles no poseen estos atributos; esto puede depender del contexto. - + + ##### Libros vs. Cursos ¡A veces distinguir puede ser dificultoso! Los cursos suelen tener libros de texto asociados, que incluiríamos en nuestras listas de libros. Además, los cursos tienen conferencias, ejercicios, pruebas, apuntes u otras ayudas didácticas. Una sola conferencia o vídeo por sí solo no es un curso. Un presentación de PowerPoint tampoco puede ser catalogado como curso. - + + ##### Tutoriales interactivos vs. Otro Material Si es posible imprimirlo y conservar su esencia, no es un Tutorial Interactivo. - + ### Automatización -- El cumplimiento de las reglas de formateado se automatiza vía [GitHub Actions](https://docs.github.com/en/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (ver [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- El cumplimiento de las reglas de formateado se automatiza vía [GitHub Actions](https://docs.github.com/en/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (ver [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - La validación de URLs se realiza mediante [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Para activar esta validación de URL, envíe un commit que incluya como mensaje de confirmación `check_urls=fichero_a_comprobar`: - ``` - check_urls=free-programming-books.md free-programming-books-en.md + ```properties + check_urls=free-programming-books.md free-programming-books-es.md ``` - Es posible especificar más de un fichero a comprobar. Simplemente use un espacio para separar cada entrada. -- Si especifica más de un archivo, los resultados obtenidos se basan en el estado del último archivo verificado. Debe tenerlo en cuenta ya que, debido a esto, puede obtener falsos positivos al finalizar el proceso. Así que tras el envío de la pull request asegúrese de inspeccionar el registro de compilación haciendo clic en "Show all checks" -> "Details". +- Si especifica más de un archivo, los resultados obtenidos se basan en el estado del último archivo verificado. Debe tenerlo en cuenta ya que, debido a esto, puede obtener falsos positivos al finalizar el proceso. Así que tras el envío de la Pull Request asegúrese de inspeccionar el registro de compilación haciendo clic en "Show all checks" -> "Details". [license]: ../LICENSE diff --git a/docs/CONTRIBUTING-fa_IR.md b/docs/CONTRIBUTING-fa_IR.md index 45089ba675711..85b1e70ea6415 100644 --- a/docs/CONTRIBUTING-fa_IR.md +++ b/docs/CONTRIBUTING-fa_IR.md @@ -1,5 +1,6 @@ *[این متن را در زبان‌های دیگر بخوانید](../README.md#translations)* +
## توافقنامه‌ی مجوز همکاری @@ -15,24 +16,27 @@ ## به طور خلاصه 1. "لینکی برای دانلود ساده‌ی یک کتاب" همیشه به معنی لینکی به یک کتاب *رایگان* نیست. لطفا فقط محتوای رایگان را قرار دهید. مطمئن شوید که این محتوا رایگان است. ما لینک‌هایی را که وارد کردن ایمیل کاری را برای دانلود کتاب *اجباری* کرده‌اند نمی‌پذیریم اما اگر بدون اجبار، این ایمیل را بخواهند، در این مخزن فهرستشان می‌کنیم. + 2. نیاز نیست گیت بلد باشید: اگر چیز جذابی پیدا کردید که *در این مخزن وجود ندارد*، یک [Issue](https://github.com/EbookFoundation/free-programming-books/issues) با نوشتن لینک‌ها درست کنید. - * اگر گیت می‌دانید، لطفا مخزن را فورک کنید و پول‌ریکوئست بفرستید. + * اگر Git را می شناسید، لطفاً مخزن را Fork کنید و درخواست های کششی (PR) ارسال کنید. + 3. ما پنج نوع فهرست داریم. فهرست درست را انتخاب کنید: * *کتاب‌ها* : PDF، HTML، ePub، سایت بر اساس gitbook.io، یک مخزن گیت و غیره. * *دوره‌ها* : دوره محتوایی آموزشی است که کتاب نیست. مثلا [این یک دوره است](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - * *آموزش‌های تعاملی* : وبسایتی تعاملی که به کاربر اجازه‌ی تایپ کد یا دستور می‌دهد و نتیجه را ارزیابی می‌کند (منظور ما از "ارزیابی"، "نمره‌دهی" نیست). مثلا: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + * *آموزش‌های تعاملی* : وبسایتی تعاملی که به کاربر اجازه‌ی تایپ کد یا دستور می‌دهد و نتیجه را ارزیابی می‌کند (منظور ما از "ارزیابی"، "نمره‌دهی" نیست). مثلا: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). * *پادکست‌ها و اسکرین‌کست‌ها* * *مجموعه مشکلات و برنامه‌نویسی رقابتی* : وبسایت یا نرم‌افزاری که به شما امکان بررسی مهارت‌های برنامه‌نویسی را با کمک حل مشکلات ساده یا پیچیده، با یا بدون بررسی کد، با یا بدون مقایسه‌ی نتایج با کاربران دیگر می‌دهد. -4. مطمئن شوید که از [راهنماها](#راهنماها) پیروی می‌کنید و طبق [فرمت‌بندی مارک‌داون](#فرمت‌بندی] می‌نویسید. +4. مطمئن شوید که از [راهنماها](#guidelines) پیروی می‌کنید و طبق [فرمت‌بندی مارک‌داون](#formatting) می‌نویسید. -5. Github Actions تست‌هایی را اجرا می‌کند که مطمئن شود فهرست شما الفبایی است و قوانین فرمت‌بندی رعایت شده است. مطمئن شوید که تغییرات شما تست‌ها را با موفقیت گذرانده است. +5. GitHub Actions تست‌هایی را اجرا می‌کند که مطمئن شود **فهرست شما الفبایی است** و **قوانین فرمت‌بندی رعایت شده است**. **مطمئن شوید که** تغییرات شما تست‌ها را با موفقیت گذرانده است. + ### راهنماها -* مطمئن شوید که یک کتاب رایگان است. اگر لازم بود، دوباره هم بررسی کنید. اگر درباره‌ی علت این که فکر می‌کنید کتاب رایگان است در پول‌ریکوئست، کامنت بگذارید، به ادمین‌ها کمک کرده‌اید. +* مطمئن شوید که یک کتاب رایگان است. اگر لازم بود، دوباره هم بررسی کنید. اگر درباره‌ی علت این که فکر می‌کنید کتاب رایگان است در پول‌ریکوئست (PR)، کامنت بگذارید، به ادمین‌ها کمک کرده‌اید. * ما فایل‌هایی را قبول نمی‌کنیم که روی گوگل‌درایو، دراپ‌باکس، مگا، اسکریبد، ایسیو یا پلتفرم‌های آپلود فایل مشابه قرار دارند * لینک‌های خود را به ترتیب الفبایی وارد کنید. اگر لینکی را خارج از ترتیب درست دیدید، لطفا مرتیش کنید و یک پی‌آر ثبت کنید * از لینک معتبرترین منبع استفاده کنید (این یعنی وبسایت نویسنده بهتر از وبسایت ویراستار و وبسایت ویراستار بهتر از وبسایت سوم شخص است) @@ -40,105 +44,111 @@ * همیشه یک لینک `https` به یک لینک `http` ترجیح داده می‌شود -- تا وقتی که هر دو لینک دامنه‌ی یکسانی داشته باشند و محتوای یکسانی نمایش دهند. * در دامنه‌های اصلی، از گذاشتن / خودداری کنید: `http://example.com` به جای `http://example.com/` * همیشه کوتاه‌ترین لینک ترجیح داده می‌شود: `http://example.com/dir/` بهتر است از `http://example.com/dir/index.html` - * از لینک‌های کوتاه‌ساز استفاده نکنید. + * از لینک‌های کوتاه‌ساز استفاده نکنید. * معمولا لینک "فعلی" بهتر از لینک "نسخه‌ها" است: `http://example.com/dir/book/current/` بهتر است از `http://example.com/dir/book/v1.0.0/index.html` * اگر لینکی مشکل certificate/self-signed certificate/SSL از هر نوع دیگری داشت: - 1. با همتای `http` همان لینک *جایگزینش کنید* (چون پذیرش استثناقائل شدن برای آن وبسایت در دستگاه‌های موبایل سخت است). - 2. اگر نسخه‌ی `http` ندارد اما همچنان با `https` و اضافه کردن استثناقائل‌شدن برای آن وبسایت در مرورگر یا نادیده گرفتن هشدار قابل دسترس است، *به همان حالت بگذاریدش* - 3. در غیر این صورت *حذفش کنید* + 1. با همتای `http` همان لینک *جایگزینش کنید* (چون پذیرش استثناقائل شدن برای آن وبسایت در دستگاه‌های موبایل سخت است). + 2. اگر نسخه‌ی `http` ندارد اما همچنان با `https` و اضافه کردن استثناقائل‌شدن برای آن وبسایت در مرورگر یا نادیده گرفتن هشدار قابل دسترس است، *به همان حالت بگذاریدش* + 3. در غیر این صورت *حذفش کنید* * اگر لینکی در چندین فرمت وجود داشت، لینکی جدا با یادداشتی درباره‌ی هر فرمت قرار دهید. * اگر منبعی در جاهای دیگری از اینترنت وجود دارد * از لینک معتبرترین منبع استفاده کنید (این یعنی وبسایت نویسنده بهتر از وبسایت ویراستار و وبسایت ویراستار بهتر از وبسایت سوم شخص است) * اگر به ویرایش‌های مختلف لینک شده است و شما معتقدید این ویرایش‌ها به حد کافی متفاوت هستند که هر دو نگه داشته شوند، یک لینک جدا با یادداشتی درباره‌ی هر ویرایش بنویسید (برای مشارکت در فرمت‌بندی [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) را ببینید). * کامیت‌های تکی (یک کامیت اضافه کردن/ حذف کردن/ تغییر دادن) بهتر از کامیت‌های بزرگ هستند. نیاز نیست کامیت‌های خود را قبل از ثبت یک پی‌آر خرد کنید (ما به دنبال اجباری کردن این قانون نیستیم چون این قانون فقط به خاطر راحتی نگه‌دارندگان مخزن است) * اگر کتاب قدیمی است، تاریخ انتشار را در کنار عنوان بنویسید. -* نام نویسنده یا نویسندگان را در صورت امکان بنویسید. می‌توانید فهرست نویسندگان را با "و همکاران" کوتاه کنید. -* اگر کتاب هنوز تمام نشده است و هنوز روی آن کار می‌شود، عبارت "in process" را همان طور که در [پایین صفحه](#in_process) آمده به آن اضافه کنید. -* اگر پیش از دانلود، نشانی ایمیل یا ساخت حساب کاربری خواسته می‌شود، در پرانتز توضیح متناسبی بنویسید. مثلا: `(نشانی ایمیل *خواسته می‌شود* اما اجباری نیست)` +* نام نویسنده یا نویسندگان را در صورت امکان بنویسید. می‌توانید فهرست نویسندگان را با "و همکاران" (به انگلیسی: "`et al.`") کوتاه کنید. +* اگر کتاب هنوز تمام نشده است و هنوز روی آن کار می‌شود، عبارت "`in process`" را همان طور که در [پایین صفحه](#in_process) آمده به آن اضافه کنید. +* اگر پیش از دانلود، نشانی ایمیل یا ساخت حساب کاربری خواسته می‌شود، در پرانتز توضیح متناسبی بنویسید. مثلا: `(نشانی ایمیل *خواسته می‌شود* اما اجباری نیست)`. + ### فرمت‌بندی * همه فهرست‌ها فایل‌های ".md" هستند. سعی کنید دستور زبان [Markdown](https://guides.github.com/features/mastering-markdown/) را یاد بگیرید. ساده است! * همه فهرست‌ها با یک فهرست محتوایی شروع می‌شود. ایده این است که همه بخش‌ها و زیربخش‌ها در این فهرست محتوایی لیست و لینک شوند. این فهرست محتوایی را به ترتیب الفبایی قرار دهید. * بخش‌ها از تیترهای سطح 3 (`###`) استفاده می‌کنند و زیربخش‌ها از تیترهای سطح 4 (`###`). + ایده این است که این موارد رعایت شوند: + * `2` خط خالی بین آخرین لینک و بخش جدید * `1` خط خالی بین تیتر و لینک اول همان بخش * `0` خط خالی بین دو لینک * `1` خط خالی در آخر هر فایل `.md` + مثال: - [...] - * [یک کتاب عالی](http://example.com/example.html) - (خط خالی) - (خط خالی) - ### مثال - (خط خالی) - * [یک کتاب عالی دیگر](http://example.com/book.html) - * [یک کتاب دیگر](http://example.com/other.html) +```text +[...] +* [یک کتاب عالی](http://example.com/example.html) + (خط خالی) + (خط خالی) +### مثال + (خط خالی) +* [یک کتاب عالی دیگر](http://example.com/book.html) +* [یک کتاب دیگر](http://example.com/other.html) +``` * بین `]` و `(` space نگذارید: -``` -بد : * [یک کتاب عالی دیگر] (http://example.com/book.html) -خوب: * [یک کتاب عالی دیگر](http://example.com/book.html) -``` + ```text + بد : * [یک کتاب عالی دیگر] (http://example.com/book.html) + خوب: * [یک کتاب عالی دیگر](http://example.com/book.html) + ``` * اگر اسم نویسنده را اضافه می‌کنید، از ` - ` استفاده کنید (یک dash با دو single space): -``` -بد : * [یک کتاب عالی دیگر](http://example.com/book.html)- نام نویسنده -خوب: * [یک کتاب عالی دیگر](http://example.com/book.html) - نام نویسنده -``` + ```text + بد : * [یک کتاب عالی دیگر](http://example.com/book.html)- نام نویسنده + خوب: * [یک کتاب عالی دیگر](http://example.com/book.html) - نام نویسنده + ``` * یک single space بین لینک و فرمت قرار دهید: -``` -بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)(PDF) -خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) (PDF) -``` + ```text + بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)(PDF) + خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) (PDF) + ``` * نویسنده قبل از فرمت می‌آید: -``` -بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)- (PDF) نام نویسنده -خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) - یک نویسنده دیگر (PDF) -``` + ```text + بد : * [یک کتاب خیلی عالی](https://example.org/book.pdf)- (PDF) نام نویسنده + خوب: * [یک کتاب خیلی عالی](https://example.org/book.pdf) - یک نویسنده دیگر (PDF) + ``` * چند فرمتی‌ها: -``` -بد : * [یک کتاب عالی دیگر](http://example.com/)- نام نویسنده (HTML) -بد : * [یک کتاب عالی دیگر](https://downloads.example.org/book.html)- نام نویسنده (download site) -خوب: * [یک کتاب عالی دیگر](http://example.com/) - نام نویسنده (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + بد : * [یک کتاب عالی دیگر](http://example.com/)- نام نویسنده (HTML) + بد : * [یک کتاب عالی دیگر](https://downloads.example.org/book.html)- نام نویسنده (download site) + خوب: * [یک کتاب عالی دیگر](http://example.com/) - نام نویسنده (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` * سال انتشار برای کتاب‌های قدیمی را در عنوان ینویسید: -``` -بد : * [یک کتاب خیلی عالی](https://example.org/book.html) - نام نویسنده - 1970 -خوب: * [یک کتاب خیلی عالی (1970)](https://example.org/book.html) - نام نویسنده -``` + ```text + بد : * [یک کتاب خیلی عالی](https://example.org/book.html) - نام نویسنده - 1970 + خوب: * [یک کتاب خیلی عالی (1970)](https://example.org/book.html) - نام نویسنده + ``` - -* کتاب‌های در دست تالیف: +* کتاب‌های در دست تالیف: + + ```text + خوب: * [کتابی که عالی خواهدشد](http://example.com/book2.html) - نام نویسنده (HTML) (:construction: *in process*) + ``` -``` -خوب: * [کتابی که عالی خواهدشد](http://example.com/book2.html) - نام نویسنده (HTML) (:construction: *in process*) -``` ### خودکارسازی -* قوانین فرمت‌بندی از طریق [Github Actions](https://docs.github.com/en/actions) با استفاده از [fpb-lint](https://github.com/vhf/free-programming-books-lint) بررسی می‌شوند ([.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml) را ببینید) +* قوانین فرمت‌بندی از طریق [GitHub Actions](https://docs.github.com/en/actions) با استفاده از [fpb-lint](https://github.com/vhf/free-programming-books-lint) بررسی می‌شوند ([`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml) را ببینید) * اعتبارسنجی لینک‌ها با استفاده از [awesome_bot](https://github.com/dkhamsing/awesome_bot) انجام می‌شود. * برای اجرای اعتبارسنجی لینک‌ها، کامیتی پوش کنید که در بدنه‌ی آن `check_urls=file_to_check` نوشته شده باشد: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-fa_IR.md + ``` * با استفاده از single space برای جدا کردن هر ورودی، می‌توانید بیشتر از یک فایل را برای بررسی مشخص کنید. -* اگر بیش از یک فایل را مشخص کردید، نتایج بیلد بر اساس نتیجه آخرین فایل بررسی‌شده خواهد بود. دقت کنید که ممکن است به همین علت، نتیجه سبز را ببینید. پس برای اطمینان لاگ بیلد را با کلیک روی "Show all checks" -> "Details" در پایان پول ریکوئست ببینید. +* اگر بیش از یک فایل را مشخص کردید، نتایج بیلد بر اساس نتیجه آخرین فایل بررسی‌شده خواهد بود. دقت کنید که ممکن است به همین علت، نتیجه سبز را ببینید. پس برای اطمینان لاگ بیلد را با کلیک روی "Show all checks" -> "Details" در پایان پول ریکوئست (PR) ببینید.
diff --git a/docs/CONTRIBUTING-fil.md b/docs/CONTRIBUTING-fil.md index 2b7e4c75f8a9d..36ac800f0c17f 100644 --- a/docs/CONTRIBUTING-fil.md +++ b/docs/CONTRIBUTING-fil.md @@ -1,61 +1,74 @@ *[Basahin ito sa ibang mga wika](../README.md#translations)* + ## Kasunduan sa Lisensya ng Contributor + Sa pamamagitan ng pag-aambag sumasang-ayon ka sa [LICENSE](../LICENSE) ng repositoryong ito. + ## Kodigo ng Pag-uugali ng Contributor + Sa pamamagitan ng pag-aambag sumasang-ayon kang igalang ang [Code of Conduct](CODE_OF_CONDUCT-fil.md) ng repositoryong ito. ([translations](../README.md#translations)) + ## Sa maikling sabi + 1. "Ang isang link para madaling mag-download ng libro" ay hindi palaging isang link sa isang *libre* na libro. Mangyaring mag-ambag lamang ng libreng nilalaman. Tiyaking libre ito. Hindi kami tumatanggap ng mga link sa mga pahina na *nangangailangan* ng gumaganang mga email address upang makakuha ng mga aklat, ngunit malugod naming tinatanggap ang mga listahan na humihiling sa kanila. + 2. Hindi mo kailangang malaman ang Git: kung nakakita ka ng isang bagay na interesado na *wala pa sa repo na ito*, mangyaring magbukas ng [Issue](https://github.com/EbookFoundation/free-programming-books/issues) kasama ang iyong mga proposisyon ng link. - Kung alam mo ang Git, mangyaring Fork ang repo at magpadala ng mga Pull Request (PR). + 3. Mayroon kaming 5 uri ng mga listahan. Piliin ang tama: - *Mga libro* : PDF, HTML, ePub, isang site na nakabatay sa gitbook.io, a Git repo, etc. - *Kurso* : Ang kurso ay isang materyal sa pag-aaral na hindi isang libro. [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Mga Interactive na Tutorial* : Isang interactive na website na nagbibigay-daan sa user na mag-type ng code o command at suriin ang resulta (sa pamamagitan ng "suriin" hindi namin ibig sabihin ay "grado"). e.g.: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Mga Interactive na Tutorial* : Isang interactive na website na nagbibigay-daan sa user na mag-type ng code o command at suriin ang resulta (sa pamamagitan ng "suriin" hindi namin ibig sabihin ay "grado"). e.g.: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Mga Podcast at Screencast* : Mga podcast at screencast. - *Mga Set ng Problema at Kompetisyon sa Programming* : Isang website o software na nagbibigay-daan sa iyong tasahin ang iyong mga kasanayan sa programming sa pamamagitan ng paglutas ng mga simple o kumplikadong problema, mayroon man o walang code review, mayroon man o walang paghahambing ng mga resulta sa ibang mga user. 4. Siguraduhing sundin ang [guidelines below](#guidelines) at igalang ang [Markdown formatting](#formatting) ng mga file. -5. Ang GitHub Actions ay magpapatakbo ng mga pagsubok upang matiyak na ang iyong mga listahan ay naka-alpabeto at sinusunod ang mga panuntunan sa pag-format. Siguraduhing suriin na ang iyong mga pagbabago ay pumasa sa mga pagsubok. +5. Ang GitHub Actions ay magpapatakbo ng mga pagsubok upang matiyak na **ang iyong mga listahan ay naka-alpabeto** at **sinusunod ang mga panuntunan sa pag-format**. **Siguraduhing** suriin na ang iyong mga pagbabago ay pumasa sa mga pagsubok. - + + ### Mga Alituntunin + - siguraduhin na ang isang libro ay libre. I-double check kung kinakailangan. Nakakatulong ito sa mga admin kung magkomento ka sa PR kung bakit sa tingin mo ay libre ang libro. - hindi kami tumatanggap ng mga file na naka-host sa Google Drive, Dropbox, Mega, Scribd, Issuu at iba pang katulad na mga platform sa pag-upload ng file - ipasok ang iyong mga link sa alphabetical order. Kung makakita ka ng maling lugar na link, mangyaring muling ayusin ito at magsumite ng PR - gamitin ang link na may pinakamakapangyarihang pinagmulan (ibig sabihin ang website ng may-akda ay mas mahusay kaysa sa website ng editor, na mas mahusay kaysa sa isang third party na website) - + walang mga serbisyo sa pagho-host ng file (kabilang dito ang (ngunit hindi limitado sa) mga link ng Dropbox at Google Drive) + - walang mga serbisyo sa pagho-host ng file (kabilang dito ang (ngunit hindi limitado sa) mga link ng Dropbox at Google Drive) - palaging mas gusto ang isang link na `https` kaysa sa isang link na `http` -- hangga't sila ay nasa parehong domain at naghahatid ng parehong nilalaman - sa mga root domain, tanggalin ang trailing slash: `http://example.com` sa halip na `http://example.com/` - palaging mas gusto ang pinakamaikling link: `http://example.com/dir/` ay mas mabuti kaysa sa `http://example.com/dir/index.html` - + walang URL shortener link + - walang URL shortener link - kadalasang mas gusto ang "kasalukuyang" link kaysa sa "bersyon": `http://example.com/dir/book/current/` ay mas mabuti kaysa sa `http://example.com/dir/book/v1.0.0/index.html` - kung ang isang link ay nag-expire na certificate/self-signed certificate/SSL isyu ng anumang iba pang uri: - 1. *palitan ito* ng katapat nitong `http` kung maaari (dahil ang pagtanggap ng mga pagbubukod ay maaaring kumplikado sa mga mobile device). - 2. *iwanan ito* kung walang available na bersyon ng `http` ngunit maa-access pa rin ang link sa pamamagitan ng `https` sa pamamagitan ng pagdaragdag ng exception sa browser o hindi papansinin ang babala. - 3. *tanggalin mo* kung hindi. + 1. *palitan ito* ng katapat nitong `http` kung maaari (dahil ang pagtanggap ng mga pagbubukod ay maaaring kumplikado sa mga mobile device). + 2. *iwanan ito* kung walang available na bersyon ng `http` ngunit maa-access pa rin ang link sa pamamagitan ng `https` sa pamamagitan ng pagdaragdag ng exception sa browser o hindi papansinin ang babala. + 3. *tanggalin mo* kung hindi. - kung mayroong isang link sa maraming format, magdagdag ng isang hiwalay na link na may tala tungkol sa bawat format - kung mayroong isang mapagkukunan sa iba't ibang lugar sa Internet - + gamitin ang link na may pinaka-makapangyarihang pinagmulan (ibig sabihin ang website ng may-akda ay mas mahusay kaysa sa website ng editor ay mas mahusay kaysa sa third party na website) - + kung nagli-link ang mga ito sa iba't ibang mga edisyon, at hinuhusgahan mo na ang mga edisyong ito ay sapat na naiiba upang maging sulit na panatilihin ang mga ito, magdagdag ng hiwalay na link na may tala tungkol sa bawat edisyon (see [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) upang mag-ambag sa talakayan sa pag-format.) + - gamitin ang link na may pinaka-makapangyarihang pinagmulan (ibig sabihin ang website ng may-akda ay mas mahusay kaysa sa website ng editor ay mas mahusay kaysa sa third party na website) + - kung nagli-link ang mga ito sa iba't ibang mga edisyon, at hinuhusgahan mo na ang mga edisyong ito ay sapat na naiiba upang maging sulit na panatilihin ang mga ito, magdagdag ng hiwalay na link na may tala tungkol sa bawat edisyon (see [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) upang mag-ambag sa talakayan sa pag-format). - mas gusto ang atomic commit (one commit by addition/deletion/modification) higit sa mas malalaking commit. Hindi na kailangang i-squash ang iyong mga commit bago magsumite ng PR. (Hindi namin kailanman ipapatupad ang panuntunang ito dahil ito ay isang bagay lamang ng kaginhawahan para sa mga nagpapanatili) - kung mas luma ang aklat, isama ang petsa ng publikasyon na may pamagat. -- isama ang pangalan ng may-akda o mga pangalan kung saan naaangkop. Maaari mong paikliin ang mga listahan ng may-akda gamit ang "`et al.`" -- kung ang aklat ay hindi pa tapos, at ginagawa pa rin, idagdag ang "in process" notation, gaya ng inilarawan [below.](#in_process) -- kung ang isang mapagkukunan ay naibalik gamit ang Wayback Machine ng Internet Archive (o katulad), idagdag ang "naka-archive" na notation, tulad ng inilarawan [below](#archived). Ang pinakamahusay na mga bersyon na gagamitin ay bago at kumpleto. -- kung humiling ng email address o pag-setup ng account bago i-enable ang pag-download, magdagdag ng mga tala na naaangkop sa wika sa mga panaklong, hal.: `(email address *requested*, not required)` +- isama ang pangalan ng may-akda o mga pangalan kung saan naaangkop. Maaari mong paikliin ang mga listahan ng may-akda gamit ang "`et al.`". +- kung ang aklat ay hindi pa tapos, at ginagawa pa rin, idagdag ang "`in process`" notation, gaya ng inilarawan [below](#in_process). +- kung ang isang mapagkukunan ay naibalik gamit ang [*Wayback Machine ng Internet Archive*](https://web.archive.org) (o katulad), idagdag ang "`naka-archive`" na notation, tulad ng inilarawan [below](#archived). Ang pinakamahusay na mga bersyon na gagamitin ay bago at kumpleto. +- kung humiling ng email address o pag-setup ng account bago i-enable ang pag-download, magdagdag ng mga tala na naaangkop sa wika sa mga panaklong, hal.: `(email address *requested*, not required)`. - + + ### Pag-format + - Ang lahat ng mga listahan ay `.md` files. Subukang matuto [Markdown](https://guides.github.com/features/mastering-markdown/) syntax. Simple lang! - Ang lahat ng mga listahan ay nagsisimula sa isang Index. Ang ideya ay ilista at i-link ang lahat ng seksyon at subsection doon. Panatilihin ito sa alpabetikong pagkakasunud-sunod. - Gumagamit ang mga seksyon ng antas 3 na mga heading (`###`), at ang mga subsection ay level 4 na mga heading (`####`). The idea is to have: + - `2` walang laman na linya sa pagitan ng huling link at bagong seksyon. - `1` walang laman na linya sa pagitan ng heading. - `0` walang laman na linya sa pagitan ng dalawang link. @@ -63,111 +76,119 @@ The idea is to have: Halimbawa: - [...] - * [An Awesome Book](http://example.com/example.html) - (blank line) - (blank line) - ### Example - (blank line) - * [Another Awesome Book](http://example.com/book.html) - * [Some Other Book](http://example.com/other.html) +```text +[...] +* [An Awesome Book](http://example.com/example.html) + (blank line) + (blank line) +### Example + (blank line) +* [Another Awesome Book](http://example.com/book.html) +* [Some Other Book](http://example.com/other.html) +``` - Huwag maglagay ng mga puwang sa pagitan `]` at `(`: -``` -BAD : * [Another Awesome Book] (http://example.com/book.html) -GOOD: * [Another Awesome Book](http://example.com/book.html) -``` + ```text + BAD : * [Another Awesome Book] (http://example.com/book.html) + GOOD: * [Another Awesome Book](http://example.com/book.html) + ``` - Kung isasama mo ang may-akda, gamitin ` - ` (isang gitling na napapalibutan ng mga solong espasyo): -``` -BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe -GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe -``` + ```text + BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe + GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe + ``` - Maglagay ng isang puwang sa pagitan ng link at ang format nito: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) + ``` - Nauna ang may-akda sa format: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Maramihang format: -``` -BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) -BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) -GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) + BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) + GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Isama ang taon ng publikasyon sa pamagat para sa mga mas lumang aklat: -``` -BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 -GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 + GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe + ``` - -- In-process books: +- In-process books: -``` -GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) -``` + ```text + GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) + ``` - -- Archived link: +- Archived link: + + ```text + GOOD: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* + ``` -``` -GOOD: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* -``` ### Mga Tala Bagama't medyo simple ang mga pangunahing kaalaman, mayroong malaking pagkakaiba-iba sa mga mapagkukunang inilista namin. Narito ang ilang tala sa kung paano natin haharapin ang pagkakaiba-iba na ito. + #### Metadata Nagbibigay ang aming mga listahan ng kaunting hanay ng metadata: mga pamagat, URL, tagalikha, platform, at tala sa pag-access. + ##### Mga pamagat - Walang naimbentong pamagat. Sinusubukan naming kumuha ng mga pamagat mula sa mga mapagkukunan mismo; ang mga nag-aambag ay pinapayuhan na huwag mag-imbento ng mga pamagat o gamitin ang mga ito sa editoryal kung ito ay maiiwasan. Ang isang pagbubukod ay para sa mas lumang mga gawa; kung pangunahin ang mga ito sa makasaysayang interes, ang isang taon sa panaklong na nakadugtong sa pamagat ay tumutulong sa mga user na malaman kung sila ay interesado. - Walang pamagat ng ALLCAPS. Kadalasan ay angkop ang title case, ngunit kapag may pagdududa, gamitin ang capitalization mula sa source + ##### URLs - Hindi namin pinahihintulutan ang mga pinaikling URL. - Dapat alisin ang mga tracking code sa URL. - Dapat na i-escape ang mga internasyonal na URL. Karaniwang nire-render ito ng mga browser bar sa Unicode, ngunit gumamit ng kopya at i-paste. -- Ang mga Secure (https) na URL ay palaging mas gusto kaysa sa mga hindi secure na (http) na mga url kung saan ipinatupad ang https. +- Ang mga Secure (`https`) na URL ay palaging mas gusto kaysa sa mga hindi secure na (`http`) na mga url kung saan ipinatupad ang HTTPS. - Hindi namin gusto ang mga URL na tumuturo sa mga webpage na hindi nagho-host ng nakalistang mapagkukunan, ngunit sa halip ay tumuturo sa ibang lugar. + ##### Mga tagalikha - Gusto naming pasalamatan ang mga lumikha ng mga libreng mapagkukunan kung saan naaangkop, kabilang ang mga tagasalin! - Para sa mga isinaling gawa ang orihinal na may-akda ay dapat na kredito. - Hindi namin pinahihintulutan ang mga link para sa Mga Tagalikha. -- Para sa compilation o remixed na mga gawa, maaaring kailanganin ng "creator" ang isang paglalarawan. Halimbawa, ang mga aklat na "GoalKicker" o "RIP Tutorial" ay kinikilala bilang "`Compiled from StackOverflow Documentation`" +- Para sa compilation o remixed na mga gawa, maaaring kailanganin ng "creator" ang isang paglalarawan. Halimbawa, ang mga aklat na "GoalKicker" o "RIP Tutorial" ay kinikilala bilang "`Compiled from StackOverflow Documentation`". + ##### Mga Platform at Mga Tala sa Pag-access - Kurso. Lalo na para sa aming mga listahan ng kurso, ang platform ay isang mahalagang bahagi ng paglalarawan ng mapagkukunan. Ito ay dahil ang mga platform ng kurso ay may iba't ibang mga affordance at mga modelo ng pag-access. Bagama't karaniwang hindi namin ilista ang isang aklat na nangangailangan ng pagpaparehistro, maraming mga platform ng kurso ang may mga affordance na hindi gumagana nang walang isang uri ng account. Kasama sa mga halimbawang platform ng kurso ang Coursera, EdX, Udacity, at Udemy. Kapag ang isang kurso ay nakasalalay sa isang platform, ang pangalan ng platform ay dapat na nakalista sa mga panaklong. -- YouTube. Marami kaming mga kurso na binubuo ng mga playlist sa YouTube. Hindi namin inilista ang Youtube bilang isang platform, sinusubukan naming ilista ang tagalikha ng Youtube, na kadalasan ay isang sub-platform. +- YouTube. Marami kaming mga kurso na binubuo ng mga playlist sa YouTube. Hindi namin inilista ang YouTube bilang isang platform, sinusubukan naming ilista ang tagalikha ng YouTube, na kadalasan ay isang sub-platform. - Mga video ng YouTube. Karaniwang hindi kami nagli-link sa mga indibidwal na video sa YouTube maliban kung ang mga ito ay higit sa isang oras ang haba at nakabalangkas tulad ng isang kurso o isang tutorial. -- Leanpub. Nagho-host ang Leanpub ng mga aklat na may iba't ibang modelo ng access. Minsan ang isang libro ay maaaring basahin nang walang pagpaparehistro; minsan ang isang libro ay nangangailangan ng isang Leanpub account para sa libreng pag-access. Dahil sa kalidad ng mga aklat at ang pinaghalong mga modelo ng pag-access sa Leanpub, pinahihintulutan namin ang paglilista ng huli kasama ang tala sa pag-access `*(Leanpub account o valid na email ang hinihiling)*` +- Leanpub. Nagho-host ang Leanpub ng mga aklat na may iba't ibang modelo ng access. Minsan ang isang libro ay maaaring basahin nang walang pagpaparehistro; minsan ang isang libro ay nangangailangan ng isang Leanpub account para sa libreng pag-access. Dahil sa kalidad ng mga aklat at ang pinaghalong mga modelo ng pag-access sa Leanpub, pinahihintulutan namin ang paglilista ng huli kasama ang tala sa pag-access `*(Leanpub account o valid na email ang hinihiling)*`. + #### Mga genre Ang unang tuntunin sa pagpapasya kung saang listahan kabilang ang isang mapagkukunan ay upang makita kung paano inilalarawan ng mapagkukunan ang sarili nito. Kung ito ay tinatawag na isang libro, marahil ito ay isang libro. + ##### Mga genre na hindi namin inililista Dahil malawak ang Internet, hindi namin isinasama sa aming mga listahan: @@ -175,7 +196,7 @@ Dahil malawak ang Internet, hindi namin isinasama sa aming mga listahan: - blogs - blog posts - articles -- websites (except for those that host LOTS of items that we list.) +- websites (except for those that host LOTS of items that we list). - videos that aren't courses or screencasts. - book chapters - teaser samples from books @@ -214,13 +235,13 @@ Kung maaari mong i-print ito at panatilihin ang kakanyahan nito, hindi ito isang ### Automation -- Ang pagpapatupad ng mga panuntunan sa pag-format ay awtomatiko sa pamamagitan ng [GitHub Actions](https://github.com/features/actions) gamit [fpb-lint](https://github.com/vhf/free-programming-books-lint) (see [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Ang pagpapatupad ng mga panuntunan sa pag-format ay awtomatiko sa pamamagitan ng [GitHub Actions](https://github.com/features/actions) gamit [fpb-lint](https://github.com/vhf/free-programming-books-lint) (see [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Gumagamit ng pagpapatunay ng URL [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Upang ma-trigger ang pagpapatunay ng URL, mag-push ng commit na may kasamang commit na mensahe na naglalaman `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-fil.md + ``` - Maaari kang tumukoy ng higit sa isang file na susuriin, gamit ang isang puwang upang paghiwalayin ang bawat entry. -- Kung tumukoy ka ng higit sa isang file, ang mga resulta ng build ay batay sa resulta ng huling file na nasuri. Dapat mong malaman na maaari kang makapasa sa mga berdeng build dahil dito kaya siguraduhing suriin ang build log sa dulo ng pull request sa pamamagitan ng pag-click sa "Show all checks" -> "Details". +- Kung tumukoy ka ng higit sa isang file, ang mga resulta ng build ay batay sa resulta ng huling file na nasuri. Dapat mong malaman na maaari kang makapasa sa mga berdeng build dahil dito kaya siguraduhing suriin ang build log sa dulo ng Pull Request sa pamamagitan ng pag-click sa "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-fr.md b/docs/CONTRIBUTING-fr.md index 80fb21eaa0ac5..4c732fe3faa90 100644 --- a/docs/CONTRIBUTING-fr.md +++ b/docs/CONTRIBUTING-fr.md @@ -1,60 +1,71 @@ *[Lisez ceci dans d'autres langues](../README.md#translations)* + ## Contrat de Licence des Contributeurs + En contribuant, vous acceptez la [LICENCE](../LICENSE) de ce repositoire. + ## Code de conduite des contributeurs + En contribuant, vous acceptez de respecter le [Code de Contrat](CODE_OF_CONDUCT-fr.md) de ce repositoire. ([translations](../README.md#translations)) + ## En bref 1. "Un lien pour télécharger facilement un livre" n'est pas toujours un lien vers un livre *gratuit*. Merci de ne contribuer qu'à du contenu gratuit. Assurez-vous que c'est gratuit. Nous n'acceptons pas les liens vers des pages qui *nécessitent* des adresses e-mail valides pour obtenir des livres, mais nous accueillons les annonces qui en font la demande. 2. Vous n'êtes pas obligé de connaître Git : si vous avez trouvé quelque chose d'intéressant qui n'est *pas déjà dans ce repositoire*, veuillez ouvrir un [Problème](https://github.com/EbookFoundation/free-programming-books/issues) avec vos propositions de liens. - - Si vous savez Git, Forkez le repo et envoyez vos pull requests. + - Si vous savez Git, Forkez le repo et envoyez vos Pull Requests (PR). + 3. Nous avons 5 types de listes. Choisissez le bon: - *Livres* : PDF, HTML, ePub, un site basé sur gitlivre.io, un repositoire Git, etc. - *Cours* : Un cours est un matériel d'apprentissage qui n'est pas un livre. [Ceci est un cours](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Tutoriels interactifs* : Un site Web interactif qui permet à l'utilisateur de saisir du code ou des commandes et d'évaluer le résultat (par "évaluer" nous ne voulons pas dire "noter"). par exemple : [Essayez Haskell](http://tryhaskell.org), [Essayez Github](http://try.github.io). + - *Tutoriels interactifs* : Un site Web interactif qui permet à l'utilisateur de saisir du code ou des commandes et d'évaluer le résultat (par "évaluer" nous ne voulons pas dire "noter"). par exemple : [Essayez Haskell](http://tryhaskell.org), [Essayez GitHub](http://try.github.io). - *Podcasts et Screencasts* : Podcasts et screencasts. - *Ensembles de Problèmes et Programmation Compétitive* : Un site Web ou un logiciel qui vous permet d'évaluer vos compétences en programmation en résolvant des problèmes simples ou complexes, avec ou sans revue de code, avec ou sans comparaison des résultats avec d'autres utilisateurs. 4. Assurez-vous de suivre les [directives ci-dessous](#directrices) et de respecter [la format Markdown](#formatage) des fichers. -5. Github Actions exécutera des tests pour s'assurer que vos listes sont classées par ordre alphabétique et que les règles de formatage sont respectées. Assurez-vous de vérifier que vos modifications passent les tests. +5. GitHub Actions exécutera des tests pour s'assurer que vos **listes sont classées par ordre alphabétique** et que **les règles de formatage sont respectées**. **Assurez-vous** de vérifier que vos modifications passent les tests. + ### Directrices + - assurez-vous qu'un livre est gratuit. Vérifiez si nécessaire. Cela aide les administrateurs si vous commentez dans le PR pourquoi vous pensez que le livre est gratuit. - nous n'acceptons pas les fichiers hébergés sur Google Drive, Dropbox, Mega, Scribd, Issuu et autres plateformes de téléchargement de fichiers similaires. - insérez vos liens par ordre alphabétique. Si vous voyez un lien égaré, veuillez le réorganiser et soumettre un PR - utiliser le lien avec la source la plus autoritaire (c'est-à-dire que le site de l'auteur est meilleur que le site de l'éditeur, qui est meilleur qu'un site tiers) - + pas de services d'hébergement de fichiers (cela inclut (mais n'est pas limité à) les liens Dropbox et Google Drive) + - pas de services d'hébergement de fichiers (cela inclut (mais n'est pas limité à) les liens Dropbox et Google Drive) - préférez toujours un lien `https` à un `http` - tant qu'ils sont sur le même domaine et servent le même contenu - sur les domaines root, supprimez la barre oblique finale: `http://exemple.com` au lieu de `http://exemple.com/` - préférez toujours le lien le plus court : `http://exemple.com/dir/` est préférable à `http://exemple.com/dir/index.html` - + pas de liens de raccourcissement d'URL + - pas de liens de raccourcissement d'URL - préférez généralement le lien "actuel" à celui de "version": `http://exemple.com/dir/livre/current/` est meilleur que `http://exemple.com/dir/livre/v1.0.0 /index.html` - si un lien a un certificat expiré/certificat auto-signé/problème SSL de toute autre nature: - 1. *remplacez-le* par son équivalent `http` si possible (car accepter les exceptions peut être compliqué sur les appareils mobiles) - 2. *laissez-le* si aucune version `http` n'est disponible mais que le lien est toujours accessible via `https` en ajoutant une exception au navigateur ou en ignorant l'avertissement. - 3. *supprimez-le* sinon. + 1. *remplacez-le* par son équivalent `http` si possible (car accepter les exceptions peut être compliqué sur les appareils mobiles) + 2. *laissez-le* si aucune version `http` n'est disponible mais que le lien est toujours accessible via `https` en ajoutant une exception au navigateur ou en ignorant l'avertissement. + 3. *supprimez-le* sinon. - si un lien existe dans plusieurs formats, ajoutez un lien séparé avec une note sur chaque format - si une ressource existe à différents endroits sur Internet - + utiliser le lien avec la source la plus autoritaire (c'est-à-dire que le site de l'auteur est meilleur que le site de l'éditeur, qui est meilleur qu'un site tiers) - + s'ils renvoient à des éditions différentes et que vous jugez que ces éditions sont suffisamment différentes pour qu'elles valent la peine d'être conservées, ajoutez un lien séparé avec une note sur chaque édition (voir [Problème #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) pour contribuer à la discussion sur le formatage.)) + - utiliser le lien avec la source la plus autoritaire (c'est-à-dire que le site de l'auteur est meilleur que le site de l'éditeur, qui est meilleur qu'un site tiers) + - s'ils renvoient à des éditions différentes et que vous jugez que ces éditions sont suffisamment différentes pour qu'elles valent la peine d'être conservées, ajoutez un lien séparé avec une note sur chaque édition (voir [Problème #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) pour contribuer à la discussion sur le formatage). - préférer les commits atomiques (un commit par ajout/suppression/modification) aux plus gros commits. Pas besoin d'écraser vos commits avant de soumettre un PR. (Nous n'appliquerons jamais cette règle car c'est juste une question de commodité pour les responsables) - si le livre est plus ancien, indiquez la date de parution avec le titre. -- incluez le ou les noms de l'auteur, le cas échéant. Vous pouvez raccourcir les listes d'auteurs avec "et al." -- si le livre n'est pas terminé, et est toujours en cours de travail, ajoutez la notation "en cours", comme décrit [ci-dessous.](#in_process) -- si une adresse e-mail ou la configuration d'un compte est demandée avant l'activation du téléchargement, ajoutez des notes adaptées à la langue entre parenthèses, par exemple: `(adresse e-mail *demandée*, non obligatoire)` +- incluez le ou les noms de l'auteur, le cas échéant. Vous pouvez raccourcir les listes d'auteurs avec "`et al.`". +- si le livre n'est pas terminé, et est toujours en cours de travail, ajoutez la notation "`en cours`", comme décrit [ci-dessous](#in_process). +- si une adresse e-mail ou la configuration d'un compte est demandée avant l'activation du téléchargement, ajoutez des notes adaptées à la langue entre parenthèses, par exemple: `(adresse e-mail *demandée*, non obligatoire)`. + ### Formatage + - Toutes les listes sont des fichiers `.md`. Essayez d'apprendre la syntaxe [Markdown](https://guides.github.com/features/mastering-markdown/). C'est simple! - Toutes les listes commencent par un Index. L'idée est d'y lister et de lier toutes les sections et sous-sections. Gardez-le par ordre alphabétique. - Les sections utilisent des titres de niveau 3 (`###`) et les sous-sections sont des titres de niveau 4 (`####`). l'idée est d'avoir: + - `2` lignes vides entre le dernier lien et la nouvelle section - `1` ligne vide entre le titre et le premier lien de sa section - `0` ligne vide entre deux liens @@ -62,104 +73,113 @@ l'idée est d'avoir: Exemple: - [...] - * [Un Livre Génial](http://exemple.com/exemple.html) - (ligne blanche) - (ligne blanche) - ### Exemple - (ligne blanche) - * [Un Autre Livre Génial](http://exemple.com/livre.html) - * [Un Autre Livre](http://exemple.com/autre.html) +```text +[..]. +* [Un Livre Génial](http://exemple.com/exemple.html) + (ligne blanche) + (ligne blanche) +### Exemple + (ligne blanche) +* [Un Autre Livre Génial](http://exemple.com/livre.html) +* [Un Autre Livre](http://exemple.com/autre.html) +``` - Mettez pas des espaces entre `]` et `(`: -``` -MAUVAIS : * [Un Autre Livre Génial] (http://exemple.com/livre.html) -BIEN : * [Un Autre Livre Génial](http://exemple.com/livre.html) -``` + ```text + MAUVAIS: * [Un Autre Livre Génial] (http://exemple.com/livre.html) + BIEN : * [Un Autre Livre Génial](http://exemple.com/livre.html) + ``` - Si vous incluez l'auteur, utilisez ` - ` (un tiret entouré d'un espaces): -``` -MAUVAIS : * [Un Autre Livre Génial](http://exemple.com/livre.html)- John Doe -BIEN : * [Un Autre Livre Génial](http://exemple.com/livre.html) - John Doe -``` + ```text + MAUVAIS: * [Un Autre Livre Génial](http://exemple.com/livre.html)- John Doe + BIEN : * [Un Autre Livre Génial](http://exemple.com/livre.html) - John Doe + ``` - Mettez un seul espace entre le lien et son format: -``` -MAUVAIS : * [Un Autre Livre Génial](https://exemple.org/livre.pdf)(PDF) -BIEN : * [Un Autre Livre Génial](https://exemple.org/livre.pdf) (PDF) -``` + ```text + MAUVAIS: * [Un Autre Livre Génial](https://exemple.org/livre.pdf)(PDF) + BIEN : * [Un Autre Livre Génial](https://exemple.org/livre.pdf) (PDF) + ``` - L'auteur vient avant le format: -``` -MAUVAIS : * [Un Autre Livre Génial](https://exemple.org/livre.pdf)- (PDF) Jane Roe -BIEN : * [Un Autre Livre Génial](https://exemple.org/livre.pdf) - Jane Roe (PDF) -``` + ```text + MAUVAIS: * [Un Autre Livre Génial](https://exemple.org/livre.pdf)- (PDF) Jane Roe + BIEN : * [Un Autre Livre Génial](https://exemple.org/livre.pdf) - Jane Roe (PDF) + ``` - Formats multiples: -``` -MAUVAIS : * [Un Autre Livre Génial](http://exemple.com/)- John Doe (HTML) -MAUVAIS : * [Un Autre Livre Génial](https://downloads.exemple.org/livre.html)- John Doe (site de téléchargement) -BIEN : * [Un Autre Livre Génial](http://exemple.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.exemple.org/livre.html) -``` + ```text + MAUVAIS: * [Un Autre Livre Génial](http://exemple.com/)- John Doe (HTML) + MAUVAIS: * [Un Autre Livre Génial](https://downloads.exemple.org/livre.html)- John Doe (site de téléchargement) + BIEN : * [Un Autre Livre Génial](http://exemple.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.exemple.org/livre.html) + ``` - Inclure l'année de publication dans le titre pour les livres plus anciens : -``` -MAUVAIS : * [Un Autre Livre Génial](https://exemple.org/livre.html) - Jane Roe - 1970 -BIEN : * [Un Autre Livre Génial (1970)](https://exemple.org/livre.html) - Jane Roe -``` + ```text + MAUVAIS: * [Un Autre Livre Génial](https://exemple.org/livre.html) - Jane Roe - 1970 + BIEN : * [Un Autre Livre Génial (1970)](https://exemple.org/livre.html) - Jane Roe + ``` - -- Livres en cours : +- Livres en cours : + + ``` + BIEN : * [Sera bientôt un livre génial](http://exemple.com/livre2.html) - John Doe (HTML) (:construction: *in process*) + ``` -``` -BIEN : * [Sera bientôt un livre génial](http://exemple.com/livre2.html) - John Doe (HTML) (:construction: *in process*) -``` ### Remarques Bien que les bases soient relativement simples, il existe une grande diversité dans les ressources que nous répertorions. Voici quelques notes sur la façon dont nous gérons cette diversité. + #### Métadonnées Nos listes fournissent un ensemble minimal de métadonnées : titres, URL, créateurs, plateformes et notes d'accès. + ##### Titres - Pas de titres inventés. Nous essayons de prendre les titres des ressources elles-mêmes ; les contributeurs sont avertis de ne pas inventer de titres ou de ne pas les utiliser éditorialement si cela peut être évité. Une exception est pour les œuvres plus anciennes; s'ils présentent principalement un intérêt historique, une année entre parenthèses ajoutée au titre aide les utilisateurs à savoir s'ils présentent un intérêt. - Pas de titres TOUTES EN MAJUSCULES. Habituellement, la casse du titre est appropriée, mais en cas de doute, utilisez la majuscule de la source + ##### URLs - Nous n'autorisons pas les URL raccourcies. - Les codes de suivi doivent être supprimés de l'URL. - Les URL internationales doivent être échappées. Les barres du navigateur les rendent généralement en Unicode, mais utilisez le copier-coller, s'il vous plaît. -- Les URL sécurisées (https) sont toujours préférées aux URL non sécurisées (http) où https a été implémenté. +- Les URL sécurisées (`https`) sont toujours préférées aux URL non sécurisées (`http`) où HTTPS a été implémenté. - Nous n'aimons pas les URL qui pointent vers des pages Web qui n'hébergent pas la ressource répertoriée, mais pointent plutôt ailleurs. + ##### Créateurs - Nous voulons créditer les créateurs de ressources gratuites le cas échéant, y compris les traducteurs ! - Pour les œuvres traduites, l'auteur original doit être crédité. - Nous n'autorisons pas les liens pour les créateurs. -- Pour les compilations ou les travaux remixés, le "créateur" peut avoir besoin d'une description. Par exemple, les livres "GoalKicker" sont crédités comme "Compilé à partir de la documentation StackOverflow" +- Pour les compilations ou les travaux remixés, le "créateur" peut avoir besoin d'une description. Par exemple, les livres "GoalKicker" sont crédités comme "`Compilé à partir de la documentation StackOverflow`" (en anglais: `Compiled from StackOverflow documentation`). + ##### Plateformes et notes d'accès - Cours. Surtout pour nos listes de cours, la plateforme est une partie importante de la description de la ressource. En effet, les plates-formes de cours ont des options et des modèles d'accès différents. Bien que nous ne répertoriions généralement pas un livre nécessitant une inscription, de nombreuses plateformes de cours ont des options qui ne fonctionnent pas sans une sorte de compte. Des exemples de plates-formes de cours incluent Coursera, EdX, Udacity et Udemy. Lorsqu'un cours dépend d'une plateforme, le nom de la plate-forme doit être indiqué entre parenthèses. -- Youtube. Nous avons de nombreux cours qui se composent de listes de lecture YouTube. Nous ne répertorions pas Youtube comme plateforme, nous essayons de répertorier le créateur Youtube, qui est souvent une sous-plateforme. -- Vidéos youtube. Nous ne créons généralement pas de liens vers des vidéos YouTube individuelles, sauf si elles durent plus d'une heure et sont structurées comme un cours ou un didacticiel. -- Leanpub. Leanpub héberge des livres avec une variété de modèles d'accès. Parfois, un livre peut être lu sans inscription ; parfois un livre nécessite un compte Leanpub pour un accès gratuit. Compte tenu de la qualité des livres et du mélange et de la fluidité des modèles d'accès Leanpub, nous autorisons l'inscription de ces derniers avec la note d'accès *(compte Leanpub ou email valide demandé)* +- YouTube. Nous avons de nombreux cours qui se composent de listes de lecture YouTube. Nous ne répertorions pas YouTube comme plateforme, nous essayons de répertorier le créateur YouTube, qui est souvent une sous-plateforme. +- Vidéos YouTube. Nous ne créons généralement pas de liens vers des vidéos YouTube individuelles, sauf si elles durent plus d'une heure et sont structurées comme un cours ou un didacticiel. +- Leanpub. Leanpub héberge des livres avec une variété de modèles d'accès. Parfois, un livre peut être lu sans inscription ; parfois un livre nécessite un compte Leanpub pour un accès gratuit. Compte tenu de la qualité des livres et du mélange et de la fluidité des modèles d'accès Leanpub, nous autorisons l'inscription de ces derniers avec la note d'accès `*(compte Leanpub ou email valide demandé)*`. + #### Genres La première règle pour décider à quelle liste appartient une ressource est de voir comment la ressource se décrit. S'il s'appelle un livre, alors c'est peut-être un livre. + ##### Genres que nous ne listons pas Parce qu'Internet est vaste, nous n'incluons pas dans nos listes: @@ -167,7 +187,7 @@ Parce qu'Internet est vaste, nous n'incluons pas dans nos listes: - les blogs - articles de blog - des articles -- des sites Web (à l'exception de ceux qui hébergent BEAUCOUP d'articles que nous répertorions.) +- des sites Web (à l'exception de ceux qui hébergent BEAUCOUP d'articles que nous répertorions). - des vidéos qui ne sont pas des cours ou des screencasts. - les chapitres du livre - échantillons teaser de livres @@ -176,6 +196,7 @@ Parce qu'Internet est vaste, nous n'incluons pas dans nos listes: Nos listes de programmation compétitive ne sont pas aussi strictes sur ces exclusions. La portée du repo est déterminée par la communauté ; si vous souhaitez suggérer un changement ou un ajout à la portée, veuillez utiliser un issue pour faire la suggestion. + ##### Livres vs. autres choses Nous ne sommes pas si pointilleux sur la livreté. Voici quelques attributs qui signifient qu'une ressource est un livre : @@ -205,13 +226,13 @@ Si vous pouvez l'imprimer et conserver son essence, ce n'est pas un didacticiel ### Automatisation -- L'application des règles de formatage est automatisée via [Github Actions](https://docs.github.com/en/actions) en utilisant [fpb-lint](https://github.com/vhf/free-programming-livres-lint) (voir [ .github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- L'application des règles de formatage est automatisée via [GitHub Actions](https://docs.github.com/en/actions) en utilisant [fpb-lint](https://github.com/vhf/free-programming-books-lint) (voir [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - La validation d'URL utilise [awesome_bot](https://github.com/dkhamsing/awesome_bot) -- Pour déclencher la validation d'URL, poussez un commit qui inclut un message de commit contenant `check_urls=file_to_check` : +- Pour déclencher la validation d'URL, poussez un commit qui inclut un message de commit contenant `check_urls=file_to_check`: -``` -check_urls=free-programming-livres.md free-programming-livres-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-fr.md + ``` - Vous pouvez spécifier plus d'un fichier à vérifier, en utilisant un seul espace pour séparer chaque entrée -- Si vous spécifiez plus d'un fichier, les résultats de la construction sont basés sur le résultat du dernier fichier vérifié. Vous devez savoir que vous pouvez obtenir des versions vertes de réussite à cause de cela, alors assurez-vous d'inspecter le journal de construction à la fin de la demande d'extraction en cliquant sur "Show all checks" -> "Details". +- Si vous spécifiez plus d'un fichier, les résultats de la construction sont basés sur le résultat du dernier fichier vérifié. Vous devez savoir que vous pouvez obtenir des versions vertes de réussite à cause de cela, alors assurez-vous d'inspecter le journal de construction à la fin de la Pull Request en cliquant sur "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-id.md b/docs/CONTRIBUTING-id.md index efe17d69bc906..eca8d7ead6377 100644 --- a/docs/CONTRIBUTING-id.md +++ b/docs/CONTRIBUTING-id.md @@ -1,42 +1,52 @@ *[Instruksi ini dalam bahasa lain](../README.md#translations)* + ## Perjanjian lisensi kontributor + Dengan kerja sama Anda, Anda menerima [lisensi](../LICENSE) dari repositori ini. + ## Kode Etik untuk Kontributor + Dengan partisipasi Anda, Anda berjanji untuk mengikuti [Kode Etik](CODE_OF_CONDUCT-id.md) dari repositori ini. ([translations](../README.md#translations)) + ## Versi pendek -1. "Tautan untuk mengunduh buku dengan mudah" tidak selalu merupakan tautan ke buku *gratis*. Harap hanya menambahkan konten gratis. Pastikan mereka gratis. Kami tidak menerima tautan ke situs yang * mengharuskan * Anda mendaftar dengan alamat email yang berfungsi untuk mengunduh buku, tetapi kami menyambut situs yang meminta alamat email. + +1. "Tautan untuk mengunduh buku dengan mudah" tidak selalu merupakan tautan ke buku *gratis*. Harap hanya menambahkan konten gratis. Pastikan mereka gratis. Kami tidak menerima tautan ke situs yang *mengharuskan* Anda mendaftar dengan alamat email yang berfungsi untuk mengunduh buku, tetapi kami menyambut situs yang meminta alamat email. + 2. Anda tidak harus terbiasa dengan Git: Jika Anda telah menemukan sesuatu yang menarik *yang belum ada di salah satu daftar*, silakan buka [Masalah](https://github.com/EbookFoundation/free-programming-books/issues) dengan tautan yang Anda sarankan. - - Jika Anda sudah familiar dengan Git, fork repositori dan kirim pull request. + - Jika Anda sudah familiar dengan Git, fork repositori dan kirim Pull Request (PR). + 3. Kami menyimpan 5 jenis daftar. Pastikan untuk memilih yang tepat: - *Buku*: PDF, HTML, ePub, halaman berdasarkan gitbook.io, repo Git, dll. - *Kursus*: Kursus menggambarkan materi pembelajaran yang tidak ada dalam bentuk buku. [Ini adalah kursus](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Tutorial interaktif*: Situs web interaktif yang memungkinkan pengguna memasukkan kode sumber atau perintah dan mengevaluasi hasilnya (dengan "mengevaluasi" kami tidak bermaksud "mengevaluasi"). misalnya: [Coba Haskell](http://tryhaskell.org), [Coba Github](http://try.github.io). + - *Tutorial interaktif*: Situs web interaktif yang memungkinkan pengguna memasukkan kode sumber atau perintah dan mengevaluasi hasilnya (dengan "mengevaluasi" kami tidak bermaksud "mengevaluasi"). misalnya: [Coba Haskell](http://tryhaskell.org), [Coba GitHub](http://try.github.io). - *Podcast dan Screencasts*: Podcast dan Screencasts. - *Kumpulan Masalah & Pemrograman Kompetitif*: Situs web atau perangkat lunak yang memberi Anda kesempatan untuk menguji keterampilan pemrograman Anda dengan memecahkan masalah sederhana atau kompleks, dengan atau tanpa tinjauan kode dan dengan atau tanpa membandingkan kinerja dengan orang lain Pengunjung situs . 4. Pastikan Anda mengikuti [Guidelines](#guidelines) dan [Markdown Formatting](#formatting) dari file. -5. GitHub Actions akan menjalankan tes untuk memastikan bahwa daftar diurutkan berdasarkan abjad dengan benar dan bahwa aturan pemformatan telah diikuti. Pastikan perubahan Anda lulus tes ini. +5. GitHub Actions akan menjalankan tes untuk memastikan bahwa **daftar diurutkan berdasarkan abjad dengan benar** dan bahwa **aturan pemformatan telah diikuti**. **Pastikan** perubahan Anda lulus tes ini. + ### Pedoman + - Pastikan sebuah buku benar-benar gratis. Periksa kembali jika perlu. Ini membantu administrator jika Anda menjelaskan dalam PR Anda mengapa menurut Anda buku tersebut gratis. - Kami tidak merekam file yang ada di Google Drive, Dropbox, Mega, Scribd, Issuu atau platform unggahan yang sebanding. - Masukkan tautan dalam urutan abjad. Jika Anda menemukan tautan yang salah dimasukkan, harap perbaiki pesanan dan buka PR. - Selalu pilih tautan dari sumber otoritatif (yaitu, situs web penulis lebih baik daripada situs web editor, yang pada gilirannya akan lebih baik daripada situs web pihak ketiga) - + tidak ada platform hosting file (termasuk tautan ke Dropbox, Google Drive, dll.) + - tidak ada platform hosting file (termasuk tautan ke Dropbox, Google Drive, dll.) - Tautan `https` harus selalu lebih disukai daripada tautan `http` - selama tautan tersebut mengarah ke domain dan konten yang sama. -- Garis miring harus dihapus pada domain root: `http://example.com` alih-alih `http://example.com/ ` +- Garis miring harus dihapus pada domain root: `http://example.com` alih-alih `http://example.com/` - Selalu pilih tautan terpendek: `http://example.com/dir/` lebih baik daripada `http://example.com/dir/index.html` - + jangan gunakan penyingkat url + - jangan gunakan penyingkat url - Pilih tautan ke versi terbaru alih-alih menautkan ke versi tertentu: `http://example.com/dir/book/current/` lebih baik daripada `http://example.com/dir/book/v1.0.0/index.html` - Jika tautan menggunakan sertifikat yang kedaluwarsa atau ditandatangani sendiri atau memiliki masalah SSL lain: - 1. *ganti* dengan mitra `http` jika memungkinkan (karena mungkin sulit untuk mengizinkan pengecualian pada perangkat seluler). - 2. *biarkan apa adanya* jika versi `http` tidak tersedia, tetapi tautan dapat diakses melalui` https` dengan mengabaikan peringatan di browser atau menambahkan pengecualian. - 3. *hapus* jika tidak. + 1. *ganti* dengan mitra `http` jika memungkinkan (karena mungkin sulit untuk mengizinkan pengecualian pada perangkat seluler). + 2. *biarkan apa adanya* jika versi `http` tidak tersedia, tetapi tautan dapat diakses melalui `https` dengan mengabaikan peringatan di browser atau menambahkan pengecualian. + 3. *hapus* jika tidak. - jika ada tautan dalam format yang berbeda, tambahkan tautan terpisah dengan referensi ke setiap format - jika sepotong konten tersedia di beberapa tempat di Internet - + pilih tautan otoritatif + - pilih tautan otoritatif diff --git a/docs/CONTRIBUTING-it.md b/docs/CONTRIBUTING-it.md index 83e5d75517f59..cee657369ff38 100644 --- a/docs/CONTRIBUTING-it.md +++ b/docs/CONTRIBUTING-it.md @@ -1,61 +1,74 @@ *[Leggilo in altre lingue](../README.md#translations)* + ## Accordo di Licenza + Contribuendo tu accetti alla [LICENZA](../LICENSE) di questa repository. + ## Codice di Comportamento del Collaboratore + I collaboratori accettano di rispettare il [Codice di Comportamento](CODE_OF_CONDUCT-it.md) di questa repository. ([translations](../README.md#translations)) + ## In breve + 1. "Un link per scaricare facilmente un libro" non è sempre un link per scaricare un libro *gratuito*. Per favore contribuisci solo con contenuti gratuiti. Assicurati che sia gratuito. Non accettiamo link a pagine che *richiedono* email funzionanti per ottenere il libro, ma diamo il benvenuto agli annunci che li richiedono. + 2. Non devi conoscere Git: se trovi qualcosa di interessante che che non è *ancora in questa repo*, apri un [Issue](https://github.com/EbookFoundation/free-programming-books/issues) con il link della risorsa. - - Se conosci Git, forka questa repository e crea una Pull Request. + - Se conosci Git, forka questa repository e crea una Pull Request (PR). + 3. Abbiamo 5 tipi di liste. Scegli quella giusta: - *Libri* : PDF, HTML, ePub, gitbook.io, una Git repo, etc. - *Corsi* : Un corso è del materiale gratuito che non è un libro. [Questo è un corso](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Tutorial Interattivi* : Un sito interattivo permette all'utente di scrivere codice o comandi e analizzarne il risultato. esempi: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Tutorial Interattivi* : Un sito interattivo permette all'utente di scrivere codice o comandi e analizzarne il risultato. esempi: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts e Screencasts* : Podcasts and screencasts. - *Set di problemi & Programmazione competitiva* : Un sito o software che ti permette di valutare le tue skills da programmatore risolvendo problemi semplici o complessi, con o senza la revisione del codice, con o senza la comparazione del risultato con gli altri utenti. 4. Assicurati di seguire le [linee guida qui sotto](#guidelines) e rispettare la [formattazione Markdown](#formatting) dei file. -5. GitHub Actions avvierà dei test per assicurarsi che le tue liste siano ordinate alfabeticamente e formattate correttamente. Assicurati che i tuoi cambiamenti passino il test. +5. GitHub Actions avvierà dei test per assicurarsi che le tue **liste siano ordinate alfabeticamente e formattate correttamente**. **Assicurati che** i tuoi cambiamenti passino il test. - + + ### Linee guida + - assicurati che il libro sia gratuito. Controlla più volte se necessario. Commentare nella PR il perché pensi che il libro sia gratuito aiuta gli admin. - non accettiamo file hostati su Google Drive, Dropbox, Mega, Scribd, Issuu e altre piattaforme simili per l'upload dei file - inserisci i link ordinandoli alfabeticamente. Se sbagli la posizione di un link, riordinalo e invia la PR - usa il link più "autorevole" per segnalare la risorsa (significa che il sito web dell'autore è migliore del sito web dell'editore, che è migliore di un sito web di terze parti) - + nessun servizio di file hosting (questo include (ma non è limitato a) link di Dropbox e Google Drive) + - nessun servizio di file hosting (questo include (ma non è limitato a) link di Dropbox e Google Drive) - preferisci sempre un link `https` rispetto ad un `http` -- purché si trovino sullo stesso dominio e contengano lo stesso contenuto - sul dominio di root, elimina il trailing slash (lo slash finale): `http://example.com` invece di `http://example.com/` - preferisci sempre link più corti: `http://example.com/dir/` è migliore di `http://example.com/dir/index.html` - + niente link accorciati + - niente link accorciati - generalmente preferisci il link "current" rispetto al link "version": `http://example.com/dir/book/current/` è migliore di `http://example.com/dir/book/v1.0.0/index.html` - se un link ha un certificato scaduto/certificato auto-firmato/problemi di SSL o di qualsiasi altro tipo: - 1. *sostituiscilo* con la controparte in `http` se possibile (perché accettare eccezione può essere complicato sui dispositivi mobile). - 2. *lascialo* se non è disponibile alcuna versione in `http` ma la versione `https` è ancora accessibile aggiungendo l'eccezione al browser o ignorando l'avviso. - 3. *rimuovilo* altrimenti. + 1. *sostituiscilo* con la controparte in `http` se possibile (perché accettare eccezione può essere complicato sui dispositivi mobile). + 2. *lascialo* se non è disponibile alcuna versione in `http` ma la versione `https` è ancora accessibile aggiungendo l'eccezione al browser o ignorando l'avviso. + 3. *rimuovilo* altrimenti. - se un link esiste in più formati, aggiungi un link separato con una nota riguardante il formato - se una risorsa è presente in posti differenti su internet - + usa il link più "autorevole" per segnalare la risorsa (significa che il sito web dell'autore è migliore del sito web dell'editore, che è migliore di un sito web di terze parti) - + se reindirizzano a edizioni differenti e tu credi che queste edizioni siano abbastanza diverse tra loro da valere la pena di essere tenute, aggiungi un link separato con una nota riguardante ogni edizione (guarda [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) per contribuire alla discussione sulla formattazione.) + - usa il link più "autorevole" per segnalare la risorsa (significa che il sito web dell'autore è migliore del sito web dell'editore, che è migliore di un sito web di terze parti) + - se reindirizzano a edizioni differenti e tu credi che queste edizioni siano abbastanza diverse tra loro da valere la pena di essere tenute, aggiungi un link separato con una nota riguardante ogni edizione (guarda [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) per contribuire alla discussione sulla formattazione). - preferisci gli atomic commits (un commit per aggiunta/modifica/eliminazione) rispetto ai grandi commit. Non c'è bisogno di raggruppare i commit per inviarli in una sola PR. (Non applichiamo mai questa regola, è solo per comodità dei moderatori) - se il libro è più vecchio, includi la data di pubblicazione assieme al titolo. -- includi il nome o i nomi degli autori se è il caso. Puoi accorciare il nome degli autori con "et al." -- se il libro non è ancora finito, e ci stanno ancora lavorando su, aggiungi "in process", come descritto [qui sotto](#in_process). Seleziona sempre l'ultima versione disponibile in questi siti. -- se una risorsa è archiviata usando la Wayback Machine di Internet Archive (o simili), aggiungi la notazione "archived", come descritto [qui sotto](#archived). La versione migliore da utilizzare è quella più recente/completa. -- se è richiesto un indirizzo email o un account per poter scaricare il libro, aggiungilo tra parentesi, esempio: `(email address *requested*, not required)` +- includi il nome o i nomi degli autori se è il caso. Puoi accorciare il nome degli autori con "`et al.`". +- se il libro non è ancora finito, e ci stanno ancora lavorando su, aggiungi "`in process`", come descritto [qui sotto](#in_process). Seleziona sempre l'ultima versione disponibile in questi siti. +- se una risorsa è archiviata usando la [*Wayback Machine di Internet Archive*](https://web.archive.org) (o simili), aggiungi la notazione "`archived`", come descritto [qui sotto](#archived). La versione migliore da utilizzare è quella più recente/completa. +- se è richiesto un indirizzo email o un account per poter scaricare il libro, aggiungilo tra parentesi, esempio: `(email address *requested*, not required)`. - + + ### Formattazione + - Tutte le liste sono file `.md`. Prova ad imparare la sintassi [Markdown](https://guides.github.com/features/mastering-markdown/). È semplice! - Tutte le liste iniziano con un Index. L'idea è di elencare e collegare tutte le sezioni e sottosezioni lì. Mantienila in ordine alfabetico. - Le sezioni utilizzano il livello 3 di heading (`###`), e le sottosezioni utilizzano il livello 4 di heading (`####`). L'idea è di avere: + - `2` linee vuote tra l'ultimo link e la nuova sezione. - `1` linea vuota tra il titolo e il primo link della sezione. - `0` linee vuote tra due link. @@ -63,111 +76,119 @@ L'idea è di avere: Esempi: - [...] - * [An Awesome Book](http://example.com/example.html) - (linea vuota) - (linea vuota) - ### Esempio - (linea vuota) - * [Another Awesome Book](http://example.com/book.html) - * [Some Other Book](http://example.com/other.html) +```text +[...] +* [An Awesome Book](http://example.com/example.html) + (linea vuota) + (linea vuota) +### Esempio + (linea vuota) +* [Another Awesome Book](http://example.com/book.html) +* [Some Other Book](http://example.com/other.html) +``` - Non mettere uno spazio tra `]` e `(`: -``` -SCORRETTO : * [Another Awesome Book] (http://example.com/book.html) -CORRETTO: * [Another Awesome Book](http://example.com/book.html) -``` + ```text + SCORRETTO: * [Another Awesome Book] (http://example.com/book.html) + CORRETTO : * [Another Awesome Book](http://example.com/book.html) + ``` - Se includi gli autori, usa ` - ` (un trattino circondato da spazi singoli): -``` -SCORRETTO : * [Another Awesome Book](http://example.com/book.html)- John Doe -CORRETTO: * [Another Awesome Book](http://example.com/book.html) - John Doe -``` + ```text + SCORRETTO: * [Another Awesome Book](http://example.com/book.html)- John Doe + CORRETTO : * [Another Awesome Book](http://example.com/book.html) - John Doe + ``` - Metti uno spazio tra il link e il formato: -``` -SCORRETTO : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) -CORRETTO: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) -``` + ```text + SCORRETTO: * [A Very Awesome Book](https://example.org/book.pdf)(PDF) + CORRETTO : * [A Very Awesome Book](https://example.org/book.pdf) (PDF) + ``` - Gli autori vanno prima del formato: -``` -SCORRETTO : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe -CORRETTO: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + SCORRETTO: * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe + CORRETTO : * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Formati multipli: -``` -SCORRETTO : * [Another Awesome Book](http://example.com/)- John Doe (HTML) -SCORRETTO : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) -CORRETTO: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + SCORRETTO: * [Another Awesome Book](http://example.com/)- John Doe (HTML) + SCORRETTO: * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) + CORRETTO : * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Includi l'anno di pubblicazione nel titolo per i libri più vecchi: -``` -SCORRETTO : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 -CORRETTO: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + SCORRETTO: * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 + CORRETTO : * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe + ``` - -- Libri in sviluppo: +- Libri in sviluppo: -``` -CORRETTO: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) -``` + ```text + CORRETTO : * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) + ``` - -- Link archiviato: +- Link archiviato: + + ```text + CORRETTO : * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* + ``` -``` -CORRETTO: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* -``` ### Note Mentre le basi sono relativamente semplici, c'è una notevole differenza tra le risorse che inseriamo nelle liste. Qui ci sono alcuni appunti su come affrontiamo queste diversità. + #### Metadata I nostri elenchi forniscono un set minimo di metadati: titoli, URLs, autori, piattaforme e note di accesso. + ##### Titoli - Non inventiamo i titoli. Cerchiamo di prendere i titoli dalla risorsa originale; i contributori sono invitati a non inventare titoli o usarli editorialmente se questo può essere evitato. Un'eccezione è per i libri più vecchi; se sono principalmente di interesse storico, l'anno tra parentesi inserito nel titolo aiuta gli utenti a capire se sono interessati a quella risorsa. - Niente titoli completamente in MAIUSCOLO. Di solito il title case è appropriato, ma in caso di dubbio usa le maiuscole utilizzate nella fonte. + ##### URLs - Non per mettiamo di rimpicciolire il link con gli appositi strumenti. - Il codice di tracciamento deve essere rimosso dall'URL. - Gli URL internazionali devono essere evitati. Le barre del browser in genere li rendono in Unicode, ma usa copia e incolla, per favore. -- I link sicuri (https) sono preferibili al posto dei link non sicuri (http), dove l'https è stato implementato. +- I link sicuri (`https`) sono preferibili al posto dei link non sicuri (`http`), dove l'HTTPS è stato implementato. - Non ci piacciono gli URL che reindirizzano in una pagina che non hosta la risorsa, ma invece reindirizza altrove. + ##### Autori - Vogliamo dare i crediti agli autori ove appropriato, anche ai traduttori! - Per i lavori tradotti, l'autore originale dovrebbe essere incluso. - Non permettiamo collegamenti per gli autori. -- Per le compilation o remix, il "creatore" potrebbe aver bisogno di una descrizione. Ad esempio, i libri "GoalKicker" o "RIP Tutorial" sono accreditati come "Compiled from StackOverflow documentation" +- Per le compilation o remix, il "creatore" potrebbe aver bisogno di una descrizione. Ad esempio, i libri "GoalKicker" o "RIP Tutorial" sono accreditati come "`Compiled from StackOverflow documentation`". + ##### Piattaforme e note di accesso - Corsi. Specialmente per la nostra liste dei corsi, la piattaforma è una parte importante della descrizione. Questo perché le varie piattaforme di corsi hanno diverse affordance e metodi di accesso. Mentre solitamente i libri non hanno bisogno di un account per essere letti, molte piattaforme di corsi ne hanno bisogno. Esempi di piattaforme di corsi sono Coursera, EdX, Udacity e Udemy. Quando un corso dipende dalla piattaforma, il suo nome dovrebbe essere incluso tra parentesi. - YouTube. Abbiamo molti corsi che consistono in playlist di YouTube. Non consideriamo YouTube come piattaforma, cerchiamo di inserire il creatore del corso, che è spesso una sotto-piattaforma. - Video YouTube. Solitamente non accettiamo singoli video YouTube, a meno che non siano più lunghi di un'ora e che siano strutturati come un corso o un tutorial. -- Leanpub. Leanpub ospita libri con varie modalità di accesso. Alcune volte i libri possono essere letti senza l'obbligo di registrazione; alcune volte è necessario creare un account gratuito su Leanpub. Data la qualità dei libri e la commistione e fluidità dei modelli di accesso Leanpub, consentiamo di elencare questi ultimi con la nota di accesso *(Leanpub account or valid email requested)* +- Leanpub. Leanpub ospita libri con varie modalità di accesso. Alcune volte i libri possono essere letti senza l'obbligo di registrazione; alcune volte è necessario creare un account gratuito su Leanpub. Data la qualità dei libri e la commistione e fluidità dei modelli di accesso Leanpub, consentiamo di elencare questi ultimi con la nota di accesso `*(Leanpub account or valid email requested)*`. + #### Generi La prima regola è decidere a quale lista appartiene di più una risorsa. Se si definisce un libro, allora forse è un libro. + ##### Generi che non accettiamo Essendo che internet è vasto, noi non accettiamo: @@ -175,7 +196,7 @@ Essendo che internet è vasto, noi non accettiamo: - blog - blog posts - articoli -- siti web (ad eccezione di quelli che ospitano MOLTI articoli che elenchiamo.) +- siti web (ad eccezione di quelli che ospitano MOLTI articoli che elenchiamo). - video che non sono corsi o screencasts. - capitoli dei libri - teaser dei libri @@ -214,13 +235,13 @@ Se riesci a stamparlo e conservarne l'essenza, non è un tutorial interattivo. ### Automazione -- L'applicazione delle regole di formattazione è automatizzata tramite [GitHub Actions](https://github.com/features/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (guarda [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- L'applicazione delle regole di formattazione è automatizzata tramite [GitHub Actions](https://github.com/features/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (guarda [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - La validazione dell'URL usa [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Per attivare la convalida dell'URL, invia un commit che includa un messaggio di commit contenente `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-it.md + ``` - È possibile specificare più di un file da controllare, utilizzando un singolo spazio per separare ogni voce. -- Se specifichi più di un file, i risultati della build si basano sul risultato dell'ultimo file controllato. Dovresti essere consapevole che potresti ottenere il passaggio di build verdi a causa di ciò, quindi assicurati di ispezionare il registro di build alla fine della richiesta pull facendo clic su "Show all checks" -> "Details". +- Se specifichi più di un file, i risultati della build si basano sul risultato dell'ultimo file controllato. Dovresti essere consapevole che potresti ottenere il passaggio di build verdi a causa di ciò, quindi assicurati di ispezionare il registro di build alla fine della Pull Request facendo clic su "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-ko.md b/docs/CONTRIBUTING-ko.md index ce8b658675912..6198e0e8d13d2 100644 --- a/docs/CONTRIBUTING-ko.md +++ b/docs/CONTRIBUTING-ko.md @@ -1,27 +1,38 @@ *[이 문서를 다른 언어로 보시려면](../README.md#translations)* + ## 기여자 라이선스 동의서 + 이 프로젝트의 기여자들은 리포지토리의 [약관](../LICENSE) 에 동의하는 것으로 간주됩니다. + ## 기여자 행도 강령 + 이 리포지토리 기여함으로서, 모든 기여자는 이 [행동강령](CODE_OF_CONDUCT-ko.md) 에 동의한 것으로 간주됩니다. ([translations](../README.md#translations)) + ## 요약 + 1. "책을 쉽게 내려받을 수 있는 바로가기"는 해당 책이 무료임을 보장하지 않습니다. 이 프로젝트에 기여하기 전에 해당 바로가기가 무료임을 확인해 주십시오. 저희는 또한 작동하는 이메일을 요구하는 바로가기는 허용하지 않습니다만, 이메일을 요청하는 것들은 허용됩니다. -2. 깃에 대해 알고 있을 필요는 없습니다: 만약 당신이 조건에 부합하면서 이미 등재되지 않은 바로가기를 발견한다면, 새로운 바로가기와 함께 새로운 [이슈](https://github.com/EbookFoundation/free-programming-books/issues)를 열 수 있습니다. - - 만약 깃 사용법을 알고 있다면, 해당 리포지토리를 Fork 하며 Pull request를 보내주세요. + +2. Git을 알 필요는 없습니다: 만약 당신이 조건에 부합하면서 *이미 등재되지 않은* 바로가기를 발견한다면, 새로운 바로가기와 함께 새로운 [이슈](https://github.com/EbookFoundation/free-programming-books/issues)를 열 수 있습니다. + - 만약 깃 사용법을 알고 있다면, 해당 리포지토리를 Fork 하며 Pull Request (PR)를 보내주세요. + 3. 저희는 다섯 가지의 리스트를 제공하고 있습니다. 올바른 것을 선택해 주세요: + - *책* : PDF, HTML, ePub, gitbook.io 기반 웹사이트, 깃 리포지토리, 등. - *강좌* : 여기서 강좌는 책이 아닌 교육 도구를 칭합니다. [강좌 예시](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *상호작용을 할 수 있는 강좌* : 사용자가 코드를 입력하거나 명령어를 입력하여 평가을 받을 수 있는 웹사이트를 칭합니다(평가는 채점이 아닙니다). 예시: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *상호작용을 할 수 있는 강좌* : 사용자가 코드를 입력하거나 명령어를 입력하여 평가을 받을 수 있는 웹사이트를 칭합니다(평가는 채점이 아닙니다). 예시: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *팟캐스트와 화면 녹화* - *문제집 & 경쟁 하며 배우는 프로그래밍* : 문제를 풂으로서 프로그래밍 실력을 향상시키는데 도움을 주는 소프트웨어 또는 웹사이트를 칭합니다. 해당 소프트웨어 또는 웹사이트는 동료가 주체가 되는 코드 검토를 포함 할 수 있습니다. 4. 아래의 [가이드라인](#가이드라인) 을 참조하고 [마크다운 규격](#규격) 을 준수하여 주십시오. -5. 깃허브 액션이 각각의 리스트가 오름차순인지, 또하 규격이 준수되었는지 검수 할 것입니다. 각 제출이 검수를 통과하는지 확인해주십시오. +5. GitHub Actions는 각각의 **리스트가 오름차순인지**, 또하 **마크다운 규격이 준수되었는지** 검수 할 것입니다. 각 제출이 검수를 통과하**는지 확인해**주십시오. + ### 가이드라인 + - 책이 무료인지 반드시 확인 해 주십시오. 해당 책이 무료라고 생각하는 이유를 PR의 comment에 포함하는 것은 관리자들에게 큰 도움이 됩니다. - 저희는 Google Drive, Dropbox, Mega, Scribd, Issuu 또는 유사한 파일 공유 시스템에 업로드된 파일들을 수락하지 않습니다. - 바로가기를 오름차순으로 정렬해 주십시오. 만약 당신이 오름차순이 아닌 파일을 발견한다면, 수정후 PR을 보내주세요. @@ -35,19 +46,22 @@ 2. `http` 버젼이 존재하지 않는다면, 기존의 링크를 사용하십시오. `https`형식또한 예외를 추가한다면 사용할 수 있습니다. 3. 이외의 경우에 *제외하십시오* - 만약 바로가기가 여러 형식으로 존재한다면, 각각을 쪽지와 함께 모두 첨부해주세요. -- 만약 자료가 여러 사이트에 분산되어 있다면, 가장 믿을 수 있는 바로가기를 첨부해주세요. 만약 각각의 바로가기가 다른 버젼으로 향한다면, 쪽지와 함께 모두 포함하십시오. (참고: [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) 해당문서는 규격에 대해 설명합니다.) +- 만약 자료가 여러 사이트에 분산되어 있다면, 가장 믿을 수 있는 바로가기를 첨부해주세요. 만약 각각의 바로가기가 다른 버젼으로 향한다면, 쪽지와 함께 모두 포함하십시오. (참고: [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) 해당문서는 규격에 대해 설명합니다). - 대량의 자료를 포함한 하나의 커밋보다는 작은 변화를 포함하는 여러개의 커밋이 선호됩니다. - 만약 오래된 책이라면, 출판일을 제목과 함께 포함하세요. -- 작가(들)의 이름을 명시하십시오. "et al."을 사용하여 단축 할 수 있습니다. -- 만약 책이 아직 완결되지 않았다면, [아래](#in_process)에 명시되어 있다시피, "in progress" 표시를 추가하십시오. -- 만약 이메일 주소 또는 계정 생성이 다운로드 이전에 요청된다면, 별도의 노트를 첨부하세요. +- 작가(들)의 이름을 명시하십시오. "`et al.`"을 사용하여 단축 할 수 있습니다. +- 만약 책이 아직 완결되지 않았다면, [아래](#in_process)에 명시되어 있다시피, "`in process`" 표시를 추가하십시오. +- 만약 이메일 주소 또는 계정 생성이 다운로드 이전에 요청된다면, 별도의 노트를 첨부하세요. 예: `(이메일 주소 *요청됨*, 필요 없음)`. + ### 규격 + - 모든 목록은 `.md`파일 형식 이어야 합니다. 해당 형식의 문법은 간단하며, [Markdown](https://guides.github.com/features/mastering-markdown/) 에서 찾아 볼 수 있습니다. - 모든 목록은 목차와 함께 시작해야 합니다. 각 항목을 목차에 연결하는 것이 목표입니다. 오름차순으로 정렬되어 있어야 합니다. - 각 섹션은 3단계 헤딩을 사용합니다 (`###`). 하위 섹션은 4단계 헤딩을 사용합니다 (`####`). 반드시 포함하여야 하는 항목들: + - 마지막 바로가기와 새로운 섹션 사이의 줄바꿈 `2`회 - 머리말과 섹션의 첫 바로가기 사이의 줄바꿈 `1`회 - 두 바로가기 사이의 줄바꿈 `0`회 @@ -55,104 +69,113 @@ 예시: - [...] - * [An Awesome Book](http://example.com/example.html) - (blank line) - (blank line) - ### Example - (blank line) - * [Another Awesome Book](http://example.com/book.html) - * [Some Other Book](http://example.com/other.html) +```text +[...] +* [An Awesome Book](http://example.com/example.html) + (blank line) + (blank line) +### Example + (blank line) +* [Another Awesome Book](http://example.com/book.html) +* [Some Other Book](http://example.com/other.html) +``` - `]` 와 `(` 사이에 공백을 넣지 마십시오: -``` -BAD : * [Another Awesome Book] (http://example.com/book.html) -GOOD: * [Another Awesome Book](http://example.com/book.html) -``` + ```text + BAD : * [Another Awesome Book] (http://example.com/book.html) + GOOD: * [Another Awesome Book](http://example.com/book.html) + ``` - 저자를 표시할 경우, ` - `를 사용하십시오 (띄어쓰기 - 띄어쓰기): -``` -BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe -GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe -``` + ```text + BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe + GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe + ``` - 바로가기와 형식 사이에는 공백을 삽입 하십시오: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) + ``` - 저자는 형식 전에 옵니다: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - 여러가지의 파일 형식이 존재할떄: -``` -BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) -BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) -GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) + BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) + GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - 오래된 책들은 출판 년도를 포함하세요: -``` -BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 -GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 + GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe + ``` - -- 작성중인 책: +- 작성중인 책: + + ```text + GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) + ``` -``` -GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) -``` ### 노트(쪽지) 각 파일의 형식은 간단하지만, 목록에는 다양한 형태와 종류의 자료들이 존재할 수 있습니다. 아래에 나열될 항목들은 저희가 그런 다양성을 어떻게 다르는지에 대한 설명 입니다. + #### 메타데이터 각 목록은 최소한의 메타데이터만을 제공합니다: 제목, 바로가기 주소, 제작자, 플랫폼, 그리고 접속 노트 + ##### 제목 - 원제를 사용하세요. 저희는 원작(원본)의 제목을 사용하기를 원합니다. 기여자들은 가능한 원제에 가깝거나 동일한 제목을 제공하여야 합니다. 예외는 오래된 책들입니다. 독자들의 더 쉬운 이해와 검색을 위해 현대의 언어로 제목을 새로 짓는것은 허가됩니다. - 대문자로만 이루어진 제목은 금지됩니다. 대부분 경우에 title case가 허가되지만, 확실하지 않다면 자료에 명시된 방식으로 기술 하세요. + ##### 바로가기 주소 - 주소 길이를 줄이는 행위는 허가되지 않습니다. - 추적을 위한 코드는 주소에서 제거되어야 합니다. - 주소에 영어가 아닌 언어가 포함 된 주소는 허가되지 않습니다. 대부분의 브라우져에서 정상적인 동작을 하지만, 주소창을 그대로 복사해주세요. 부탁드립니다. -- 보안 주소(https)가 존재하는 경우, 보안 주소가 일반 주소(http)보다 선호됩니다. +- 보안 주소(`https`)가 존재하는 경우, 보안 주소가 일반 주소(`http`)보다 선호됩니다. - 설명과 다른 웹페이지로 향하는 바로가기 주소는 선호되지 않습니다. + ##### 제작자 - 저희는 무료로 자료들을 배포하는 제작자들(번역가들 포함)에게 감사함을 표합니다! - 번역된 자료들의 경우, 원작자들이 우선적으로 명시되어야 합니다. - 제작자들의 정보로 향하는 바로가기 주소는 허가되지 않습니다. -- 여러 작업물이 조합된 자료의 경우, "제작자"는 설명이 필요할 수 있습니다. 예를 들어, "GoalKicker" 책들의 제작자들은 "Compiled from StackOverflow documentation"로 명시되어야 합니다. +- 여러 작업물이 조합된 자료의 경우, "제작자"는 설명이 필요할 수 있습니다. 예를 들어, "GoalKicker" 책들의 제작자들은 "`Compiled from StackOverflow documentation`"로 명시되어야 합니다. + ##### 플랫폼과 접속 노트 - 강좌, 특히 걍좌 목록의 경우, 플랫폼을 명시하는것이 필수적입니다. 각각의 강좌들의 플랫폼을 추가하여야 무료로 접속할 수 있음을 이용자들이 인지 할 수 있습니다. 일반적으로 로그인이 필요한 책은 목록에 포함하지 않지만, 강좌는 대부분 계정을 생성하지 않으면 접근 할 수 없기 때문에 예외로 합니다. 예시로는 Coursera, EdX, Udacity, 그리고 Udemy가 있습니다. 해당 강좌들이 플랫폼 의존적이라면, 플랫폼의 이름은 반드시 포함되어야 합니다. -- 만약 강좌가 유튜브에 존재하는 경우, 유튜브는 플랫폼으로 간주하지 않고, 크리에이터를 명시합니다. -- 유튜브 영상들은 각각의 영상이 한시간이 넘지 않는 경우에는 바로가기 주소를 포함하지 않습니다. -- Leanpub는 많은 책들과 강좌에 접근을 제공합니다. 경우에 따라 회원가입 없이 접근 할 수 있는 책들 또한 존재합니다. 경우에 따라 *(Leanpub account or valid email requested)* 노트를 포함하여 목록을 작성해야 합니다. +- 유튜브. YouTube 재생 목록으로 구성된 많은 과정이 있습니다. YouTube를 플랫폼으로 나열하지 않고 종종 하위 플랫폼인 YouTube 제작자를 나열하려고 합니다. +- 유튜브 동영상. 우리는 일반적으로 1시간 이상 길이가 코스나 튜토리얼처럼 구성되지 않는 한 개별 YouTube 동영상에 링크하지 않습니다. +- Leanpub는 많은 책들과 강좌에 접근을 제공합니다. 경우에 따라 회원가입 없이 접근 할 수 있는 책들 또한 존재합니다. 경우에 따라 `*(Leanpub account or valid email requested)*` 노트를 포함하여 목록을 작성해야 합니다. + #### 장르 자료가 어떤 장르에 속하는지 결정하는 첫번째 방법은 해당 자료의 분류에 따르는 것입니다. + ##### 기술하지않는 장르 인터넷에는 너무 다양하고 정확하지않은 자료들이 있기에, 저희는 다음 장르를 포함하지 않습니다: @@ -191,6 +214,7 @@ GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe 강좌는 종종 책을 보조교재로 사용하는데, 이것은 상기한 책의 특성에 의해 목록에 추가 될 수 있습니다. 이 보조교재에는 종종 강의 노트, 연습 문제, 시험, 등등이 포함됩니다. 영상/강의 하나는 강좌로 간주되지 않습니다. 또한, 파워포인트는 강좌가 아닙니다. + ##### 상호작용 강의 vs. 다른 자료 만약 강의가 인쇄되어서도 사용 될 수 있다면, 상호작용 강의에 포함되지 않습니다. @@ -198,13 +222,13 @@ GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe ### 자동화 -- 규격 규칙은 [GitHub Actions](https://github.com/features/actions)에 의해 [fpb-lint](https://github.com/vhf/free-programming-books-lint)를 사용하여 강제됩니다 (see [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- 규격 규칙은 [GitHub Actions](https://github.com/features/actions)에 의해 [fpb-lint](https://github.com/vhf/free-programming-books-lint)를 사용하여 강제됩니다 (see [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - 바로가기 주소 검증은 [awesome_bot](https://github.com/dkhamsing/awesome_bot)를 이용합니다 - 바로가기 주소 검증을 위해 커밋 메시지에 `check_urls=file_to_check`을 포함해 주세요: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-ko.md + ``` - 각 입력을 공백으로 구문하여 하나 이상의 파일을 검사 할 수 있습니다. - 만약 하나 이상의 파일을 검사한다면, 검사 결과는 마지막 파일의 검사 결과가 표시됩니다. 이 특성으로 인하여 통과를 받았더라도 관리자에 의하여 최종 승인이 보류 될 수 있습니다. 정확한 결과를 확인 하려면, "Show all checks" -> "Details"로 가세요. diff --git a/docs/CONTRIBUTING-pt_BR.md b/docs/CONTRIBUTING-pt_BR.md index e6bb43ff0a9b0..292b2fc3a70c3 100644 --- a/docs/CONTRIBUTING-pt_BR.md +++ b/docs/CONTRIBUTING-pt_BR.md @@ -1,59 +1,71 @@ *[Leia em outros idiomas](../README.md#translations)* + ## Acordo de Licença do Contribuidor + Ao contribuir você concorda com a [LICENSE](../LICENSE) deste repositório. + ## Código de Conduta do Contribuidor + Ao contribuir você concorda em respeitar o [Código de Conduta](CODE_OF_CONDUCT-pt_BR.md) deste repositório. ([translations](../README.md#translations)) + ## Em poucas palavras + 1. "Um _link_ para baixar um livro facilmente" nem sempre é um _link_ para um livro *gratuito*. Por favor contribua apenas com conteúdo gratuito. Certifique-se de que é grátis. Não são aceitos _links_ para páginas que *requerem* um endereço de email para obter livros, mas aceitamos listas que requerem. 2. Não é necessário saber Git: se você encontrou algo interessante que *não está presente neste repositório*, por favor abra uma [Issue](https://github.com/EbookFoundation/free-programming-books/issues) com todas as propostas de _links_. - - Se você sabe Git, faça um _Fork_ do repositório e mande um _pull request_. + - Se você sabe Git, faça um _Fork_ do repositório e mande um _Pull Request (PR)_. 3. Possuimos 5 tipos de listas. Escolha a mais adequada: + - *Livros*: PDF, HTML, ePub, sites baseados no gitbook.io, um repositório Git, etc. - *Cursos*: Um curso é um material didático que não é um livro. [Isso é um curso](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Tutoriais Interativos*: Um site interativo que permite ao usuário digitar código ou comandos e computa o resulta (por "computar" não queremos dizer "avaliar"). Por exemplo: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Tutoriais Interativos*: Um site interativo que permite ao usuário digitar código ou comandos e computa o resulta (por "computar" não queremos dizer "avaliar"). Por exemplo: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts e Screencasts* : Podcasts e screencasts. - *Conjuntos de Problemas e Programação Competitiva* : Um site ou software que permite avaliar suas habilidades de programação através da resolução de problemas simples ou complexos, com ou sem revisão de código, com ou sem comparação de resultados com outros usuários. 4. Certifique-se de seguir as [diretrizes abaixo](#diretrizes) e respeitar a [formatação de Markdown](#formatação) dos arquivos. -5. GitHub Actions executará testes para assegurar que suas listas estão em ordem alfabética e seguem as regras de formatação. Cerfique-se de que suas alterações passaram pelos testes. +5. GitHub Actions executará testes para assegurar que suas **listas estão em ordem alfabética** e **seguem as regras de formatação**. **Cerfique-se** de que suas alterações passaram pelos testes. + ### Diretrizes + - certifique-se de que o livro é gratuito. Verifique múltiplas vezes se necessário. Comentar no PR por quê você acha que o livro é gratuito ajuda os administradores. - não aceitamos arquivos hospedados no Google Drive, Dropbox, Mega, Scribd, Issuu e outras plataformas similares de _upload_ de arquivos. - insira seus _links_ em ordem alfabética. Se vir um _link_ fora de ordem, por favor reordene-o e crie um PR. - use o _link_ com a fonte mais oficial (isso significa que o site do próprio autor é melhor que o site da editora, que é melhor que sites de terceiros) - + sem serviços de hospedagem de arquivos (isso inclui (mas não se limita a) _links_ do Dropbox e Google Drive) + - sem serviços de hospedagem de arquivos (isso inclui (mas não se limita a) _links_ do Dropbox e Google Drive) - sempre prefira um _link_ `https` em vez de `http` -- desde que estejam no mesmo domínio e sirvam o mesmo conteúdo. - em domínios raiz, remova a barra final: `http://exemplo.com` ao invés de `http://exemplo.com/` - sempre prefira o _link_ mais curto: `http://exemplo.com/dir/` é melhor que `http://exemplo.com/dir/index.html` - + sem _links_ vindos de encurtadores de _links_ + - sem _links_ vindos de encurtadores de _links_ - prefira o _link_ "_current_" ao invés de _"version"_: `http://exemplo.com/dir/book/current/` é melhor que `http://exemplo.com/dir/book/v1.0.0/index.html` - se um _link_ possui um certificado expirado/autoassinado/problema de SSL de qualquer outro tipo: - 1. *substitua-o* por seu equivalente `http` se possível (pois aceitar exceções pode ser complicado em dispositivos móveis). - 2. *mantenha-o* se não houver versão `http` disponível, mas o _link_ continua acessível através de `https` adicionando uma exceção ao browser ou ignorando o aviso. - 3. *remova-o* caso contrário. + 1. *substitua-o* por seu equivalente `http` se possível (pois aceitar exceções pode ser complicado em dispositivos móveis). + 2. *mantenha-o* se não houver versão `http` disponível, mas o _link_ continua acessível através de `https` adicionando uma exceção ao browser ou ignorando o aviso. + 3. *remova-o* caso contrário. - se o _link_ existir em múltiplos formatos, adicione um _link_ separado com uma observação sobre cada formato. - se o material existe em diferentes lugares na Internet - + use o _link_ com a fonte mais oficial (isso significa que o site do autor é melhor que o site da editora que é melhor que sites de terceiros) - + se eles referenciam diferentes edições, e você julgar que essas edições são diferentes o bastante para mantê-las, adicione um _link_ separado com uma observação para cada edição (veja [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) para contribuir com a discussão sobre formatação). + - use o _link_ com a fonte mais oficial (isso significa que o site do autor é melhor que o site da editora que é melhor que sites de terceiros) + - se eles referenciam diferentes edições, e você julgar que essas edições são diferentes o bastante para mantê-las, adicione um _link_ separado com uma observação para cada edição (veja [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) para contribuir com a discussão sobre formatação). - prefira _commits_ atômicos (um _commit_ para cada adição/deleção/modificação) ao invés de _commits_ maiores. Não é necessário fazer o _squash_ de seus _commits_ antes de submeter um PR. Nunca iremos impor esta regra dado que é apenas uma questão de conveniência para os mantenedores). - se o livro for mais antigo, inclua a data de publicação no título. -- inclua o(s) nome(s) do(s) autor(es) onde for apropriado. Você pode encurtar a lista de autores com "et al". -- se o livro não estiver completo, e ainda está sendo escrito, adicione a notação "em processo", como descrito [abaixo.](#em_processo) +- inclua o(s) nome(s) do(s) autor(es) onde for apropriado. Você pode encurtar a lista de autores com "`et al`". +- se o livro não estiver completo, e ainda está sendo escrito, adicione a notação "`in process`", como descrito [abaixo](#in_process). - se um endereço de email ou configuração de conta for solicitado antes que o _download_ seja habilitado, adicione uma observação no idioma apropriado e entre parênteses. Por exemplo: `(endereço de email é *pedido*, não obrigatório)`. + ### Formatação + - Todas as listas são arquivos `.md`. Tente aprender a sintaxe de [Markdown](https://guides.github.com/features/mastering-markdown/). É simples! - Todas as listas começam com um Índice. A ideia é listar e "_linkar_" todas as seções e subseções lá. Mantenha-o em ordem alfabética. - Seções são títulos de nível 3 (`###`), e subseções são títulos de nível 4 (`####`). A ideia é ter: + - `2` linhas em branco entre o último _link_ e a nova seção. - `1` linha em branco entre o título e o primeiro _link_ da seção. - `0` linhas em branco entre dois _links_. @@ -61,104 +73,113 @@ A ideia é ter: Exemplo: - [...] - * [Um Livro Incrível](http://exemplo.com/exemplo.html) - (linha em branco) - (linha em branco) - ### Exemplo - (linha em branco) - * [Outro Livro Incrível](http://exemplo.com/livro.html) - * [Outro Livro Qualquer](http://exemplo.com/outro.html) +```text +[...] +* [Um Livro Incrível](http://exemplo.com/exemplo.html) + (linha em branco) + (linha em branco) +### Exemplo + (linha em branco) +* [Outro Livro Incrível](http://exemplo.com/livro.html) +* [Outro Livro Qualquer](http://exemplo.com/outro.html) +``` - Não coloque espaços entre `]` e `(`: -``` -RUIM : * [Outro Livro Incrível] (http://exemplo.com/livro.html) -BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html) -``` + ```text + RUIM: * [Outro Livro Incrível] (http://exemplo.com/livro.html) + BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html) + ``` - Se incluir o autor, use ` - ` (um traço envolto por espaços simples): -``` -RUIM : * [Outro Livro Incrível](http://exemplo.com/livro.html)- Fulano de Tal -BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html) - Fulano de Tal -``` + ```text + RUIM: * [Outro Livro Incrível](http://exemplo.com/livro.html)- Fulano de Tal + BOM : * [Outro Livro Incrível](http://exemplo.com/livro.html) - Fulano de Tal + ``` - Coloque um espaço simples entre o _link_ e seu formato: -``` -RUIM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)(PDF) -BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) (PDF) -``` + ```text + RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)(PDF) + BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) (PDF) + ``` - Autor vem antes do formato: -``` -RUIM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)- (PDF) Fulana de Tal -BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) - Fulana de Tal (PDF) -``` + ```text + RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf)- (PDF) Fulana de Tal + BOM : * [Um Livro Muito Incrível](https://exemplo.org/livro.pdf) - Fulana de Tal (PDF) + ``` - Múltiplos formatos: -``` -RUIM : * [Outro Livro Incrível](http://exemplo.com/)- Fulano de Tal (HTML) -RUIM : * [Outro Livro Incrível](https://downloads.exemplo.org/livro.html)- Fulano de Tal (download site) -BOM : * [Outro Livro Incrível](http://exemplo.com/) - Fulano de Tal (HTML) [(PDF, EPUB)](https://downloads.exemplo.org/livro.html) -``` + ```text + RUIM: * [Outro Livro Incrível](http://exemplo.com/)- Fulano de Tal (HTML) + RUIM: * [Outro Livro Incrível](https://downloads.exemplo.org/livro.html)- Fulano de Tal (download site) + BOM : * [Outro Livro Incrível](http://exemplo.com/) - Fulano de Tal (HTML) [(PDF, EPUB)](https://downloads.exemplo.org/livro.html) + ``` - Inclua o ano de publicação no título de livros antigos: -``` -RUIM : * [Um Livro Muito Incrível](https://exemplo.org/livro.html) - Fulana de Tal - 1970 -BOM : * [Um Livro Muito Incrível (1970)](https://exemplo.org/livro.html) - Fulana de Tal -``` + ```text + RUIM: * [Um Livro Muito Incrível](https://exemplo.org/livro.html) - Fulana de Tal - 1970 + BOM : * [Um Livro Muito Incrível (1970)](https://exemplo.org/livro.html) - Fulana de Tal + ``` - -- Livros em processo: +- Livros em processo: + + ```text + BOM : * [Será Um Livro Incrível Em Breve](http://exemplo.com/livro2.html) - Fulano de Tal (HTML) (:construction: *em processo*) + ``` -``` -BOM : * [Será Um Livro Incrível Em Breve](http://exemplo.com/livro2.html) - Fulano de Tal (HTML) (:construction: *em processo*) -``` ### Observações As noções básicas são relativamente simples, mas há uma grande diversidade de materiais que listamos. Aqui estão algumas observações sobre como tratamos essa diversidade. + #### Metadados Nossas listas fornecem um conjunto mínimo de metadados: títulos, URLs, criadores, plataformas e notas de acesso. + ##### Títulos - Sem títulos inventados. Tentamos utilizar os títulos dos próprios materiais; contribuidores são aconselhados a não inventar títulos ou usá-los editorialmente se possível evitar. Uma exceção é para trabalhos antigos; se forem primariamente de interesse histórico, o ano entre parênteses adicionado ao título ajuda os usuários a saber se é de seu interesse. - Sem título EM CAIXA ALTA. Normalmente "_title case_" é apropriado. Em caso de dúvida, use a capitalização da fonte. + ##### URLs - Não permitimos encurtadores de URLs. - Códigos de rastreamento devem ser removidos da URL. - URLs internacionais devem ser escapadas. Barras de endereço dos navegadores normalmente renderizam eles em Unicode, mas use copiar e colar, por favor. -- URLs seguras (https) sempre são preferidas no lugar de URLs não-seguras (http) quando https estiver disponível. +- URLs seguras (`https`) sempre são preferidas no lugar de URLs não-seguras (`http`) quando HTTPS estiver disponível. - Não gostamos de URLs que apontam para páginas que não hospedam o material listado, mas apontam para outro lugar. + ##### Criadores - Queremos creditar os criadores do material gratuito apropriadamente, incluindo tradutores! - Para trabalhos traduzidos, o autor original deve ser creditado. - Não permitimos _links_ para Criadores. -- Para compilações ou trabalhos remixados, o "criador" pode precisar de uma descrição. Por exemplo, os livros "GoalKicker" são creditados como "Compilado da documento do StackOverflow" +- Para compilações ou trabalhos remixados, o "criador" pode precisar de uma descrição. Por exemplo, os livros "GoalKicker" são creditados como "`Compilado da documento do StackOverflow`" (em inglês: "`Compiled from StackOverflow documentation`"). + ##### Plataforma e Notas de Acesso - Cursos. Especificamente para nossa lista de cursos, a plataforma é uma parte importante da descrição do material. Isso acontece pois plataformas de cursos possuem _affordances_ e modelos de acesso diferentes. Normalmente não listamos um livro que requer um cadastro, muitas plataformas de cursos possuem _affordances_ que não funcionam sem algum tipo de conta. Exemplos de plataformas de cursos incluem Coursera, EdX, Udacity, e Udemy. Quando o curso depende da plataforma, o nome da plataforma deve ser listado em parênteses. - YouTube. Temos muitos cursos que consistem em _playlists_ do YouTube. Não listamos YouTube como uma plataforma, tentamos listar o criador no YouTube, que normalmente é uma subplataforma. - Vídeos do YouTube. Normalmente não usamos vídeos do YouTube individuais a não ser que tenham mais de uma hora e sejam estruturados como um curso ou tutorial. -- Leanpub. Leanpub hospeda livros com uma variedade de modelos de acesso. Algumas vezes, um livro pode ser lido sem necessidade de registro; algumas vezes um livro requer uma conta Leanpub para acesso gratuito. Dada a qualidade dos livros e a mistura e fluidez dos modelos de acesso do Leanpub, permitimos a listagem deste com uma observação de acesso *(Conta Leanpub ou email válido solicitado)* +- Leanpub. Leanpub hospeda livros com uma variedade de modelos de acesso. Algumas vezes, um livro pode ser lido sem necessidade de registro; algumas vezes um livro requer uma conta Leanpub para acesso gratuito. Dada a qualidade dos livros e a mistura e fluidez dos modelos de acesso do Leanpub, permitimos a listagem deste com uma observação de acesso `*(Conta Leanpub ou email válido solicitado)*`. + #### Gêneros A primeira regra ao decidir a qual lista um material pertence é ver como o próprio material se descreve. Se diz que é um livro, então talvez seja um livro. + ##### Gêneros não listados Dada a vastidão da Internet, não incluimos em nossas listas: @@ -205,13 +226,13 @@ Se você pode capturar a tela ou imprimí-la e reter sua essência, então não ### Automação -- Aplicação das regras de formatação é automatizada via [GitHub Actions](https://github.com/features/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (veja [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Aplicação das regras de formatação é automatizada via [GitHub Actions](https://github.com/features/actions) usando [fpb-lint](https://github.com/vhf/free-programming-books-lint) (veja [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Validação de URL usa [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Para ativar a validação de URL, dê _push_ num _commit_ que inclua uma mensagem de _commit_ contendo `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-pt_BR.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-pt_BR.md + ``` - Você pode especificar mais de um arquivo para checagem, usando um espaço simples para separar cada entrada. -- Se você especificar mais de um arquivo, os resultados de _build_ serão baseados no resultado do último arquivo verificado. Você deve se atentar para o fato de que pode obter um _build_ com verde de sucesso devido a isso. Então, certifique-se de inspecionar o _build log_ ao final de cada _pull request_ clicando em "Show all checks" -> "Details". +- Se você especificar mais de um arquivo, os resultados de _build_ serão baseados no resultado do último arquivo verificado. Você deve se atentar para o fato de que pode obter um _build_ com verde de sucesso devido a isso. Então, certifique-se de inspecionar o _build log_ ao final de cada _Pull Request_ clicando em "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-ru.md b/docs/CONTRIBUTING-ru.md index 899204e3bfc30..991ef2c2dc8af 100644 --- a/docs/CONTRIBUTING-ru.md +++ b/docs/CONTRIBUTING-ru.md @@ -1,67 +1,76 @@ *[Доступно на других языках](../README.md#translations)* - + + ## Лицензионное соглашение с участником Принимая участие, вы соглашаетесь с [ЛИЦЕНЗИЕЙ](../LICENSE) этого репозитория. - + + ## Кодекс поведения автора Принимая участие, вы соглашаетесь соблюдать [Кодекс поведения](CODE_OF_CONDUCT-ru.md) этого репозитория. ([translations](../README.md#translations)) - + + ## В двух словах 1. «Ссылка для легкой загрузки книги» не всегда является ссылкой на *бесплатную* книгу. Пожалуйста, размещайте только бесплатный контент. Убедитесь, что это бесплатно. Мы не принимаем ссылки на страницы, которым *требуются* адреса электронной почты на рабочем домене для получения книг. Однако мы приветствуем списки, которые запрашивают их. + 2. Вам необязательно знать Git: если вы нашли что-то интересное, чего *еще нет в этом репозитории*, пожалуйста, откройте [Issue](https://github.com/EbookFoundation/free-programming-books/issues) с вашими предложениями. - - Если вы знакомы с Git, пожалуйста форкните репозиторий и пришлите пулреквест. + - Если вы знакомы с Git, пожалуйста форкните репозиторий и пришлите пулреквест (PR). + 3. У нас есть 5 видов списков. Выберите подходящий: - *Книги*: PDF, HTML, ePub, сайт на основе gitbook.io, репозиторий Git и т. Д. - *Курсы*: курс - это учебный материал, который не является книгой. [Это курс](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Интерактивные учебные пособия*: интерактивный веб-сайт, который позволяет пользователю вводить код или команды и оценивать результат (под «результатом» мы не подразумеваем «оценку»). например: [Попробуйте Haskell](http://tryhaskell.org), [Попробуйте Github](http://try.github.io). + - *Интерактивные учебные пособия*: интерактивный веб-сайт, который позволяет пользователю вводить код или команды и оценивать результат (под «результатом» мы не подразумеваем «оценку»). например: [Попробуйте Haskell](http://tryhaskell.org), [Попробуйте GitHub](http://try.github.io). - *Подкасты и скринкасты*: подкасты и скринкасты. - *Наборы задач и соревновательное программирование*: веб-сайт или программа, которое позволяет вам оценить свои навыки программирования, решая простые или сложные задачи, с проверкой кода или без нее, со сравнением результатов с результатами других пользователей или без него. 4. Обязательно следуйте [Руководству, приведённому ниже](#guidelines) и соблюдайте [Markdown форматирование](#formatting) файлов. -5. GitHub Actions запустит тесты, чтобы убедиться, что ваши списки отсортированы по алфавиту и соблюдаются правила форматирования. Обязательно проверьте, чтобы ваши изменения прошли проверку. +5. GitHub Actions запустит тесты, чтобы убедиться, что ваши **списки отсортированы по алфавиту** и **соблюдаются правила форматирования**. **Обязательно проверьте**, чтобы ваши изменения прошли проверку. - + + ### Руководство - Убедитесь что книга бесплатна. При необходимости проверьте еще раз. Администраторам помогает, если вы описываете в PR, почему вы думаете, что книга бесплатная. - Мы не принимаем файлы, размещенные на Google Drive, Dropbox, Mega, Scribd, Issuu и других подобных платформах для загрузки файлов. - Вставляйте ссылки в алфавитном порядке. Если вы видите ссылку нарушающую порядок, измените ее порядок и отправьте PR - Используйте ссылку с наиболее авторитетным источником (то есть сайт автора лучше, чем сайт редактора, что лучше, чем сторонний сайт) - + не с файловых хостингов (включая (но не ограничиваясь) ссылками на Dropbox и Google Drive) -- всегда предпочитайте ссылку https вместо ссылки http - если они находятся в одном домене и обслуживают один и тот же контент + - не с файловых хостингов (включая (но не ограничиваясь) ссылками на Dropbox и Google Drive) +- всегда предпочитайте ссылку `https` вместо ссылки `http` - если они находятся в одном домене и обслуживают один и тот же контент - в корневых доменах удалите косую черту в конце: `http://example.com` вместо `http://example.com/` - всегда предпочитайте самую короткую ссылку: `http://example.com/dir/` лучше, чем `http://example.com/dir/index.html` - + избегайте сервисы сокращения ссылок + - избегайте сервисы сокращения ссылок - Обычно предпочитают ссылку на "актуальную" версию, чем на конкретную: `http://example.com/dir/book/current/` лучше, чем `http://example.com/dir/book/v1.0.0/index.html` - Если ссылка имеет просроченный сертификат/самоподписанный сертификат/SSL-сертификат любого другого типа: 1. *замените её* его эквивалентом http, если это возможно (поскольку принятие исключений может быть затруднено на мобильных устройствах). - 2. *оставьте её*, если версия http недоступна, но ссылка все еще доступна через https путем добавления исключения в браузер или игнорирования предупреждения. + 2. *оставьте её*, если версия http недоступна, но ссылка все еще доступна через `https` путем добавления исключения в браузер или игнорирования предупреждения. 3. *удалите* в противном случае. - Если ссылка существует в нескольких форматах, добавьте отдельную ссылку с примечанием о каждом формате - Если ресурс существует в разных местах в Интернете - + используйте ссылку с наиболее авторитетным источником (это означает, что сайт автора лучше, чем сайт редактора, лучше, чем сторонний сайт) - + если они ссылаются на разные выпуски и вы считаете, что эти выпуски достаточно разные, чтобы их стоило сохранить, добавьте отдельную ссылку с примечанием о каждом выпуске (см. [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353), чтобы обсудить форматирование.) + - используйте ссылку с наиболее авторитетным источником (это означает, что сайт автора лучше, чем сайт редактора, лучше, чем сторонний сайт) + - если они ссылаются на разные выпуски и вы считаете, что эти выпуски достаточно разные, чтобы их стоило сохранить, добавьте отдельную ссылку с примечанием о каждом выпуске (см. [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353), чтобы обсудить форматирование). - Предпочитайте атомарные коммиты (по одному коммиту на каждое добавление/удаление/модификацию) большим коммитам. Не нужно собирать все коммиты в один перед тем, как отправить PR. (Мы никогда не будем настаивать на этом, поскольку это просто вопрос удобства для сопровождающих) - Если книга более старая, укажите дату публикации в названии. -- Укажите имя автора или имена там, где это необходимо. Вы можете сократить списки авторов с помощью «и др.». -- если книга не закончена, и работа над ней продолжается, добавьте пометку «в процессе», как описано [ниже.](#in_process) -- если перед загрузкой запрашивается адрес электронной почты или настройка учетной записи, добавьте в скобки примечания на соответствующем языке, например: `(адрес электронной почты *запрашивают*, но он не требуется для загрузки)` +- Укажите имя автора или имена там, где это необходимо. Вы можете сократить списки авторов с помощью «`и др.`» («`et al.`»). +- если книга не закончена, и работа над ней продолжается, добавьте пометку «`в процессе`», как описано [ниже](#in_process). +- если перед загрузкой запрашивается адрес электронной почты или настройка учетной записи, добавьте в скобки примечания на соответствующем языке, например: `(адрес электронной почты *запрашивают*, но он не требуется для загрузки)`. + - + ### Форматирование -- Все списки представляют собой файлы с расширением .md. Попробуйте изучить синтаксис [Markdown](https://guides.github.com/features/mastering-markdown/). Это просто! + +- Все списки представляют собой файлы с расширением `.md`. Попробуйте изучить синтаксис [Markdown](https://guides.github.com/features/mastering-markdown/). Это просто! - Все списки начинаются с индекса. Идея состоит в том, чтобы перечислить и связать там все разделы и подразделы. Храните их в алфавитном порядке. - В разделах используются заголовки уровня 3 (`###`), а в подразделах используются заголовки уровня 4 (`####`). Идея состоит в том, чтобы иметь: + - `2` пустые строки между последней ссылкой и новым разделом. - `1` пустую строку между заголовком и первой ссылкой его раздела. - `0` пустых ссылок между двумя ссылками. @@ -69,111 +78,121 @@ Пример: - [...] - * [Шикарная книга](http://example.com/example.html) - (пустая строка) - (пустая строка) - ### Пример - (пустая строка) - * [Другая шикарная книга](http://example.com/book.html) - * [Ещё одна другая книга](http://example.com/other.html) +```text +[...] +* [Шикарная книга](http://example.com/example.html) + (пустая строка) + (пустая строка) +### Пример + (пустая строка) +* [Другая шикарная книга](http://example.com/book.html) +* [Ещё одна другая книга](http://example.com/other.html) +``` - Не вставляйте пробел между `]` и `(`: -``` -ПЛОХО : * [Другая шикарная книга] (http://example.com/book.html) -ХОРОШО: * [Другая шикарная книга](http://example.com/book.html) -``` + ```text + ПЛОХО : * [Другая шикарная книга] (http://example.com/book.html) + ХОРОШО: * [Другая шикарная книга](http://example.com/book.html) + ``` - Если вы указываете автора, используйте ` - ` (тире, окруженное одиночными пробелами): -``` -ПЛОХО : * [Другая шикарная книга](http://example.com/book.html)- Джон Доу -ХОРОШО: * [Другая шикарная книга](http://example.com/book.html) - Джон Доу -``` + ```text + ПЛОХО : * [Другая шикарная книга](http://example.com/book.html)- Джон Доу + ХОРОШО: * [Другая шикарная книга](http://example.com/book.html) - Джон Доу + ``` - Отбейте ссылку и её формат пробелом: -``` -ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)(PDF) -ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) (PDF) -``` + ```text + ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)(PDF) + ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) (PDF) + ``` - Сперва автор, потом формат: -``` -ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)- (PDF) Джейн Роу -ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) - Джейн Роу (PDF) -``` + ```text + ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)- (PDF) Джейн Роу + ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) - Джейн Роу (PDF) + ``` - Несколько форматов: -``` -ПЛОХО : * [Другая шикарная книга](http://example.com/)- Джон Доу (HTML) -ПЛОХО : * [Другая шикарная книга](https://downloads.example.org/book.html)- Джон Доу (cайт для загрузки) -ХОРОШО: * [Другая шикарная книга](http://example.com/) - Джон Доу (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + ПЛОХО : * [Другая шикарная книга](http://example.com/)- Джон Доу (HTML) + ПЛОХО : * [Другая шикарная книга](https://downloads.example.org/book.html)- Джон Доу (cайт для загрузки) + ХОРОШО: * [Другая шикарная книга](http://example.com/) - Джон Доу (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` -- Включите год публикации в заголовок для старых книг: +- Включите год публикации в заголовок для старых книг: -``` -ПЛОХО : * [Очень хорошая книга](https://example.org/book.html) - Джейн Роу - 1970 -ХОРОШО: * [Очень хорошая книга (1970)](https://example.org/book.html) - Джейн Роу -``` + ```text + ПЛОХО : * [Очень хорошая книга](https://example.org/book.html) - Джейн Роу - 1970 + ХОРОШО: * [Очень хорошая книга (1970)](https://example.org/book.html) - Джейн Роу + ``` - -- Незавершенные книги: +- Незавершенные книги: -``` -ХОРОШО: * [Скоро будет отличная книга](http://example.com/book2.html) - Джон Доу (HTML) (:construction: *in process*) -``` - + ```text + ХОРОШО: * [Скоро будет отличная книга](http://example.com/book2.html) - Джон Доу (HTML) (:construction: *in process*) + ``` + + + ### Примечания Хотя основы относительно просты, перечисленные нами ресурсы очень разнообразны. Вот несколько замечаний о том, как мы справляемся с этим разнообразием. - + + #### Метаданные Наши списки предоставляют минимальный набор метаданных: заголовки, URL-адреса, создателей, платформы и примечания к доступу. - + + ##### Заголовки - Никаких вымышленных названий. Мы стараемся брать названия с самих ресурсов; призываем авторов пулреквестов не придумывать заголовки и не использовать их в редакционных целях, если этого можно избежать. Исключение составляют более старые работы; если они представляют в первую очередь исторический интерес, год в скобках, добавленный к названию, помогает пользователям узнать, представляют ли они интерес. - Избегайте заголовков ПОЛНОСТЬЮ ЗАГЛАВНЫМИ БУКВАМИ. Обычно уместен регистр заголовка, но в случае сомнений используйте заглавные буквы из источника. - + + ##### URLs - Мы не разрешаем сокращенные URL-адреса. - Коды отслеживания должны быть удалены из URL. - Международные URL-адреса должны быть экранированы. Адресная панель браузера обычно отображают их в Unicode, но, пожалуйста, используйте копирование и вставку. -- Безопасные (https) URL-адреса всегда предпочтительнее небезопасных (http) URL-адресов, в которых реализован https. +- Безопасные (`https`) URL-адреса всегда предпочтительнее небезопасных (`http`) URL-адресов, в которых реализован HTTPS. - Нам не нравятся URL-адреса, которые указывают на страницы со ссылкой на другое место вместо указанного ресурса. - + + ##### Creators - Хотим поблагодарить создателей бесплатных ресурсов, где это возможно, в том числе переводчиков! - Для переведенных работ следует указать оригинального автора. - Мы не разрешаем ссылки на авторов. -- Для подборок и смешенных изданий «создателю» может потребоваться описание. Например, книги «GoalKicker» считаются «Скомпилированными из документации StackOverflow». +- Для подборок и смешенных изданий «создателю» может потребоваться описание. Например, книги «GoalKicker» считаются «`Скомпилированными из документации StackOverflow`» ("на английском: «`Compiled from StackOverflow documentation`»). - + + ##### Платформы и примечания к доступу - Курсы. Платформа является важной частью описания ресурсов, особенно для наших списков курсов. Это связано с тем, что платформы курсов имеют разные возможности и модели доступа. Хотя мы обычно не перечисляем книги, требующие регистрации, на многих платформах курсов есть возможности, которые не работают без какой-либо учетной записи. Например, как на Coursera, EdX, Udacity и Udemy. Если курс зависит от платформы, название платформы должно быть указано в скобках. -- YouTube. У нас есть много курсов, состоящих из плейлистов YouTube. Мы не указываем Youtube как платформу, мы пытаемся указать автора на Youtube, который часто является под-платформой. +- YouTube. У нас есть много курсов, состоящих из плейлистов YouTube. Мы не указываем YouTube как платформу, мы пытаемся указать автора на YouTube, который часто является под-платформой. - YouTube видео. Обычно мы не ссылаемся на отдельные видео YouTube, если они не длится более часа или не структурированы как курс или учебное пособие. -- Leanpub. Leanpub размещает книги с различными моделями доступа. Иногда книгу можно прочитать без регистрации; иногда для бесплатного доступа к книге требуется учетная запись Leanpub. Учитывая качество книг, а также сочетание и гибкость моделей доступа к Leanpub, мы разрешаем перечисление последних с указанием доступа *(требуется учетная запись Leanpub или действующий адрес электронной почты)* +- Leanpub. Leanpub размещает книги с различными моделями доступа. Иногда книгу можно прочитать без регистрации; иногда для бесплатного доступа к книге требуется учетная запись Leanpub. Учитывая качество книг, а также сочетание и гибкость моделей доступа к Leanpub, мы разрешаем перечисление последних с указанием доступа `*(требуется учетная запись Leanpub или действующий адрес электронной почты)*`. + - + #### Жанры Первое правило при принятии решения, к какому списку принадлежит ресурс, — это посмотреть, как ресурс описывает себя. Если он называет себя книгой, то, возможно, это книга. - + + ##### Жанры, которые мы не вносим в списки Поскольку Интернет огромен, мы не включаем в наши списки: @@ -181,7 +200,7 @@ - блоги - Сообщения в блоге - статьи -- веб-сайты (за исключением тех, размещающих МНОГО элементов которые мы перечисляем.) +- веб-сайты (за исключением тех, размещающих МНОГО элементов которые мы перечисляем). - видео, не являющиеся курсами или скринкастами. - главы книги - ознакомительные образцы из книг @@ -190,7 +209,8 @@ В наших списках соревновательного программирования эти исключения не так строги. Объем репо определяется сообществом; если вы хотите предложить изменение или дополнение к области, пожалуйста, используйте Issue, чтобы сделать предложение. - + + ##### Книги против прочих ресурсов Мы не так привередливы в "книжности" ресурса. Вот некоторые атрибуты, которые указывают на то, что ресурс - это книга: @@ -205,28 +225,31 @@ Мы перечисляем множество книг, у которых нет этих атрибутов; это может зависеть от контекста. - + + ##### Книги против курсов Иногда их бывает трудно отличить! С курсами часто связаны учебники, которые мы перечисляем в наших списках книг. В курсах есть лекции, упражнения, тесты, заметки или другие дидактические пособия. Отдельная лекция или видео - это не курс. PowerPoint - это не курс. - + + ##### Интерактивные учебники и другие материалы Если вы можете распечатать его и сохранить его суть, это не интерактивное руководство. - + + ### Автоматизация -- Применение правил форматирования автоматизировано с помощью [GitHub Actions](https://github.com/features/actions) с использованием [fpb-lint](https://github.com/vhf/free-programming-books-lint) (см. [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Применение правил форматирования автоматизировано с помощью [GitHub Actions](https://github.com/features/actions) с использованием [fpb-lint](https://github.com/vhf/free-programming-books-lint) (см. [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Для проверки URL используется [awesome_bot](https://github.com/dkhamsing/awesome_bot) -- Чтобы запустить проверку URL, нажмите фиксацию, которая включает сообщение фиксации, содержащее `check_urls = ссылка_для_проверки`: +- Чтобы запустить проверку URL, нажмите фиксацию, которая включает сообщение фиксации, содержащее `check_urls=ссылка_для_проверки`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-ru.md + ``` - Вы можете указать более одного файла для проверки, используя один пробел для разделения каждой записи. - Если вы укажете более одного файла, результаты сборки будут основаны на результате последнего проверенного файла. Вы должны знать, что из-за этого вы можете получить проходящие зеленые сборки, поэтому обязательно проверьте журнал сборки в конце пулреквеста, нажав "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-vi.md b/docs/CONTRIBUTING-vi.md index f66744176e0c4..9f6d09283d05d 100644 --- a/docs/CONTRIBUTING-vi.md +++ b/docs/CONTRIBUTING-vi.md @@ -2,67 +2,80 @@ Bản dịch Tiếng Việt: -* Bản dịch này mục đích để khuyến khích các bạn đóng góp vào dự án `free-programming-books` mà chưa thể đọc tốt được Tiếng Anh. Tôi cũng mong Việt Nam có thể có nhiều hơn những khóa học, những cuốn sách miễn phí về lập trình để giúp các bạn trẻ hiện nay có thể sớm tiếp cận với công nghệ, phát triển sớm được niềm đam mê của bản thân. +- Bản dịch này mục đích để khuyến khích các bạn đóng góp vào dự án `free-programming-books` mà chưa thể đọc tốt được Tiếng Anh. Tôi cũng mong Việt Nam có thể có nhiều hơn những khóa học, những cuốn sách miễn phí về lập trình để giúp các bạn trẻ hiện nay có thể sớm tiếp cận với công nghệ, phát triển sớm được niềm đam mê của bản thân. -* Tôi đã cố gắng dịch chính xác, nhưng khó có thể tránh khỏi một số sai sót, mong các bạn lượng thứ. +- Tôi đã cố gắng dịch chính xác, nhưng khó có thể tránh khỏi một số sai sót, mong các bạn lượng thứ. -* Mọi ý kiến, đóng góp về bản dịch, vui lòng [tạo một issue mới](/issues/new) hoặc bạn có thể chỉnh sửa và tạo pull Request. +- Mọi ý kiến, đóng góp về bản dịch, vui lòng [tạo một issue mới](/issues/new) hoặc bạn có thể chỉnh sửa và tạo pull Request. --- + ## Giấy Phép Thỏa Thuận Cộng Tác Viên + Bằng cách đóng góp, bạn đồng ý với [LICENSE](../LICENSE) của kho lưu trữ này. + ## Quy Tắc Ứng Xử của Cộng Tác Viên + Bằng cách đóng góp, bạn đồng ý tôn trọng [Quy Tắc Ứng Xử](CODE_OF_CONDUCT.md) của kho lưu trữ này. ([translations](../README.md#translations)) + ## Tóm Tắt + 1. "Một liên kết để tải một cuốn sách" không có nghĩa nó là một cuốn sách *miễn phí*. Vui lòng chỉ đóng góp nội dung miễn phí. Đảm bảo rằng nó là miễn phí. Chúng tôi không chấp nhận các liên kết đến các trang có *yêu cầu bắt buộc* nhập địa chỉ email để nhận sách, nhưng chúng tôi hoan nghênh những danh sách yêu cầu chúng. + 2. Bạn không cần phải biết về Git: nếu bạn tìm được thứ gì đó thú vị *và chưa có trong kho lưu trữ này*, vui lòng mở một [Issue](https://github.com/EbookFoundation/free-programming-books/issues) với các đề xuất mà bạn muốn đóng góp. - - Nếu bạn biết Git, vui lòng Fork kho lưu trữ này và gửi pull requests. + - Nếu bạn biết Git, vui lòng Fork kho lưu trữ này và gửi Pull Requests (PR). + 3. Chúng tôi có 5 loại tài liệu, bạn có thể chọn một trong những cái dưới đây: - *Sách* : PDF, HTML, ePub, một trang web dựa trên gitbook.io, một kho lưu trữ Git, v.v. - *Khóa Học* : Một khóa học là một tài liệu học tập, không phải là sách. [Đây là một khóa học](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Hướng Dẫn Trực Quan* : Một trang web cho phép người dùng lập trình hoặc chạy chương trình dựa trên kết quả và đánh giá. Ví dụ: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Hướng Dẫn Trực Quan* : Một trang web cho phép người dùng lập trình hoặc chạy chương trình dựa trên kết quả và đánh giá. Ví dụ: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts và Screencasts* : Podcasts và screencasts. - *Bài Tập & Cuộc Thi Lập Trình* : Trang web hoặc phần mềm cho phép bạn đánh giá kỹ năng lập trình của mình bằng cách giải quyết các vấn đề đơn giản hoặc phức tạp, có hoặc không có đánh giá mã nguồn, có hoặc không so sánh kết quả với những người khác. 4. Đảm bảo tuân thủ theo [những nguyên tắc bên dưới](#Những Nguyên Tắc) và đảm bảo sử dụng đúng [định dạng Markdown](#Định Dạng). -5. Github Actions sẽ chạy các test để đảm bảo danh sách của bạn được sắp xếp theo thứ tự bảng chữ cái và các nguyên tắc định dạng được tuân thủ. Kiểm tra để đảm bảo các thay đổi của bạn có vượt qua các bài test. +5. GitHub Actions sẽ chạy các test để đảm bảo **danh sách của bạn được sắp xếp theo thứ tự bảng chữ cái** và các **nguyên tắc định dạng được tuân thủ**. **Kiểm tra để đảm bảo** các thay đổi của bạn có vượt qua các bài test. + ### Những Nguyên Tắc + - đảm bảo rằng một cuốn sách là miễn phí. Kiểm tra kỹ nếu cần. Nó sẽ giúp cho các quản trị viên nếu bạn nhận xét trong phần PR về lý do tại sao bạn cho rằng cuốn sách là miễn phí. - chúng tôi không chấp nhận các tệp được lưu trữ trên Google Drive, Dropbox, Mega, Scribd, Issuu và các nền tảng tải lên tệp tương tự khác. - chèn các liên kết của bạn theo thứ tự bảng chữ cái. Nếu bạn thấy một liên kết bị đặt sai vị trí, vui lòng sắp xếp lại nó và gửi một PR. - sử dụng liên kết với nguồn có thẩm quyền nhất (có nghĩa là trang web của tác giả tốt hơn trang web của người biên tập, tốt hơn trang web của bên thứ ba) - + không có dịch vụ lưu trữ tệp (điều này bao gồm (nhưng không giới hạn) liên kết Dropbox và Google Drive) + - không có dịch vụ lưu trữ tệp (điều này bao gồm (nhưng không giới hạn) liên kết Dropbox và Google Drive) - một giao thức `https` tốt hơn giao thức `http` - miễn là chúng ở trên cùng một domain và thể hiện cùng một nội dung. - trên các miền gốc, bỏ dấu gạch chéo sau: `http://example.com` thay vì `http://example.com/` - luôn luôn ưu tiên đường dẫn ngắn: `http://example.com/dir/` tốt hơn là `http://example.com/dir/index.html` - + không sử dụng link rút gọn + - không sử dụng link rút gọn - thường ưu tiên những liên kết "mới nhất" hơn những liên kết có "phiên bản (version)": `http://example.com/dir/book/current/` tốt hơn `http://example.com/dir/book/v1.0.0/index.html` - nếu một liên kết có chứng chỉ hết hạn như chứng chỉ/ tự chứng chỉ / chứng chỉ SSL hoặc các vấn đề tương tự: - 1. *thay thế nó* bằng giao thức `http` nếu có thể (bởi vì việc chấp nhận các lỗi ngoại lệ có thể phức tạp trên các thiết bị di động) - 2. *giữ nguyên* nếu không thể sử dụng `http` nhưng liên kết có thể truy cập được thông qua `https` bằng cách thêm một ngoại lệ vào trình duyệt hoặc có thể bỏ qua cảnh báo - 3. *xóa nó đi* nếu không thể làm gì khác + 1. *thay thế nó* bằng giao thức `http` nếu có thể (bởi vì việc chấp nhận các lỗi ngoại lệ có thể phức tạp trên các thiết bị di động) + 2. *giữ nguyên* nếu không thể sử dụng `http` nhưng liên kết có thể truy cập được thông qua `https` bằng cách thêm một ngoại lệ vào trình duyệt hoặc có thể bỏ qua cảnh báo + 3. *xóa nó đi* nếu không thể làm gì khác - nếu một liên kết tồn tại ở nhiều định dạng, hãy thêm một ghi chú riêng về từng định dạng - nếu một tài liệu tồn tại ở những nơi khác nhau trên Internet - + sử dụng liên kết với nguồn có thẩm quyền nhất (có nghĩa là trang web của tác giả tốt hơn trang web của người biên tập và tốt hơn trang web của bên thứ ba) - + nếu chúng liên kết đến các ấn bản khác nhau và bạn đánh giá các ấn bản này đủ khác nhau để có giá trị giữ chúng, hãy thêm một ghi chú riêng về từng ấn bản (xem [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) để đóng góp vào cuộc thảo luận về định dạng.) + - sử dụng liên kết với nguồn có thẩm quyền nhất (có nghĩa là trang web của tác giả tốt hơn trang web của người biên tập và tốt hơn trang web của bên thứ ba) + - nếu chúng liên kết đến các ấn bản khác nhau và bạn đánh giá các ấn bản này đủ khác nhau để có giá trị giữ chúng, hãy thêm một ghi chú riêng về từng ấn bản (xem [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) để đóng góp vào cuộc thảo luận về định dạng). - ưu tiên các commit nhỏ (atomic commits - một commit chỉ có thêm, xóa hoặc sửa) hơn các commit lớn. Không cần phải giấu các commits của bạn trước khi gửi PR. (Chúng tôi sẽ không bao giờ thực thi những thứ này vì nó thuận tiện sau này cho người bảo trì) - nếu sách cũ, hãy bao gồm ngày xuất bản cùng với tên sách. -- bao gồm tên tác giả hoặc tên nếu thích hợp. Bạn có thể rút ngắn danh sách tác giả với "et al." -- nếu cuốn sách chưa hoàn thành và vẫn đang được hoàn thiện, hãy thêm ký hiệu "đang xử lý", như được mô tả [dưới đây.](#in_process) -- nếu địa chỉ email hoặc thiết lập tài khoản được yêu cầu trước khi kích hoạt tải xuống, hãy thêm ghi chú phù hợp với ngôn ngữ trong ngoặc đơn, ví dụ: `(địa chỉ email *được yêu cầu*, không bắt buộc)` +- bao gồm tên tác giả hoặc tên nếu thích hợp. Bạn có thể rút ngắn danh sách tác giả với "`et al.`". +- nếu cuốn sách chưa hoàn thành và vẫn đang được hoàn thiện, hãy thêm ký hiệu "`đang xử lý`", như được mô tả [dưới đây](#in_process). +- nếu địa chỉ email hoặc thiết lập tài khoản được yêu cầu trước khi kích hoạt tải xuống, hãy thêm ghi chú phù hợp với ngôn ngữ trong ngoặc đơn, ví dụ: `(địa chỉ email *được yêu cầu*, không bắt buộc)`. + ### Định Dạng + - Tất cả danh sách đều là tệp `.md`. Cố gắng học các cú pháp [Markdown](https://guides.github.com/features/mastering-markdown/). Nó rất đơn giản! - Tất cả các danh sách bắt đầu bằng một Chỉ mục. Ý tưởng là liệt kê và liên kết tất cả các phần và tiểu mục ở đó. Giữ nó theo thứ tự bảng chữ cái. - Các phần đang sử dụng tiêu đề cấp 3 (`###`) và các tiểu mục là tiêu đề cấp 4 (`####`). Ý tưởng là phải có + - `2` dòng trống giữa liên kết cuối cùng và phần mới - `1` dòng trống giữa tiêu đề và liên kết đầu tiên của phần của nó - `0` dòng trống giữa hai liên kết @@ -70,104 +83,113 @@ Bằng cách đóng góp, bạn đồng ý tôn trọng [Quy Tắc Ứng Xử](C Ví dụ: - [...] - * [Một cuốn sách tuyệt vời](http://example.com/example.html) - (dòng trống) - (dòng trống) - ### Ví dụ - (dòng trống) - * [Một cuốn sách tuyệt vời khác](http://example.com/book.html) - * [Một số sách khác](http://example.com/other.html) +```text +[...] +* [Một cuốn sách tuyệt vời](http://example.com/example.html) + (dòng trống) + (dòng trống) +### Ví dụ + (dòng trống) +* [Một cuốn sách tuyệt vời khác](http://example.com/book.html) +* [Một số sách khác](http://example.com/other.html) +``` - Không đặt dấu cách giữa `]` và `(`: -``` -Tệ : * [Một cuốn sách tuyệt vời khác] (http://example.com/book.html) -Tốt: * [Một cuốn sách tuyệt vời khác](http://example.com/book.html) -``` + ```text + TỆ : * [Một cuốn sách tuyệt vời khác] (http://example.com/book.html) + TỐT: * [Một cuốn sách tuyệt vời khác](http://example.com/book.html) + ``` - Nếu bao gồm tác giả, hãy sử dụng ` - ` (dấu gạch ngang được bao quanh bởi các khoảng trắng): -``` -Tệ : * [Một cuốn sách tuyệt vời khác](http://example.com/book.html)- John Doe -Tốt: * [Một cuốn sách tuyệt vời khác](http://example.com/book.html) - John Doe -``` + ```text + TỆ : * [Một cuốn sách tuyệt vời khác](http://example.com/book.html)- John Doe + TỐT: * [Một cuốn sách tuyệt vời khác](http://example.com/book.html) - John Doe + ``` - Đặt một khoảng trắng giữa liên kết và định dạng của nó: -``` -Tệ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf)(PDF) -Tốt: * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf) (PDF) -``` + ```text + TỆ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf)(PDF) + TỐT: * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf) (PDF) + ``` - Tác giả đặt trước định dạng: -``` -Tệ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf)- (PDF) Jane Roe -Tốt: * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + TỆ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf)- (PDF) Jane Roe + TỐT: * [Một cuốn sách rất tuyệt vời](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Nhiều định dạng: -``` -Tệ : * [Một cuốn sách tuyệt vời khác](http://example.com/)- John Doe (HTML) -Tệ : * [Một cuốn sách tuyệt vời khác](https://downloads.example.org/book.html)- John Doe (download site) -Tốt: * [Một cuốn sách tuyệt vời khác](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + TỆ : * [Một cuốn sách tuyệt vời khác](http://example.com/)- John Doe (HTML) + TỆ : * [Một cuốn sách tuyệt vời khác](https://downloads.example.org/book.html)- John Doe (download site) + TỐT: * [Một cuốn sách tuyệt vời khác](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Bao gồm năm xuất bản trong tiêu đề cho các sách cũ hơn: -``` -Tệ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.html) - Jane Roe - 1970 -Tốt: * [Một cuốn sách rất tuyệt vời (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + TỆ : * [Một cuốn sách rất tuyệt vời](https://example.org/book.html) - Jane Roe - 1970 + TỐT: * [Một cuốn sách rất tuyệt vời (1970)](https://example.org/book.html) - Jane Roe + ``` - -- Sách đang trong quá trình viết: +- Sách đang trong quá trình viết: + + ```text + TỐT: * [Sách sẽ sớm trở nên tuyệt vời](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) + ``` -``` -Tốt: * [Sách sẽ sớm trở nên tuyệt vời](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) -``` ### Ghi Chú Mặc dù những điều cơ bản tương đối đơn giản, nhưng có sự đa dạng lớn trong các nguồn mà chúng tôi liệt kê. Dưới đây là một số lưu ý về cách chúng ta phân loại những sự đa dạng này. + #### Metadata Danh sách của chúng tôi cung cấp một metadata: tiêu đề, URL, người tạo, nền tảng và ghi chú truy cập. + ##### Tiêu Đề - Không được phát minh ra tiêu đề. Chúng tôi cố gắng lấy các tiêu đề từ chính các nguồn tài liệu đó; những người đóng góp được khuyến cáo không phát minh ra tiêu đề hoặc chỉnh sửa chúng nếu điều này có thể tránh được. Một ngoại lệ là đối với các tác phẩm cũ hơn; nếu họ chủ yếu quan tâm đến lịch sử, thêm số năm vào trong dấu ngoặc đơn nằm trong tiêu đề sẽ giúp người dùng biết liệu họ có quan tâm hay không. -- Không sử dụng tiêu đề viết hoa toàn bộ. Thông thường, viết hoa tiêu đề là phù hợp, nhưng khi không chắc chắn, hãy sử dụng chữ viết hoa từ nguồn. +- Không sử dụng tiêu đề viết HOA TOÀN BỘ. Thông thường, viết hoa tiêu đề là phù hợp, nhưng khi không chắc chắn, hãy sử dụng chữ viết hoa từ nguồn. + ##### Các Liên Kết - Chúng tôi không cho phép các liên kết rút gọn. - Mã theo dõi phải được xóa khỏi liên kết. - Liên kết quốc tế phải được thoát. Các thanh trình duyệt thường hiển thị chúng thành Unicode, nhưng vui lòng sử dụng sao chép và dán. -- Các liên kết an toàn (https) luôn được ưu tiên hơn các liên kết không an toàn (http) nơi https đã được triển khai. +- Các liên kết an toàn (`https`) luôn được ưu tiên hơn các liên kết không an toàn (``http`) nơi HTTPS đã được triển khai. - Chúng tôi không thích các liên kết trỏ đến các trang web không lưu trữ tài liệu được liệt kê, mà thay vào đó trỏ đến nơi khác. + ##### Người Sáng Tạo - Chúng tôi muốn ghi công những người tạo ra các tài liệu miễn phí nếu thích hợp, bao gồm cả những người dịch! - Đối với các tác phẩm đã dịch, tác giả gốc nên được ghi công. - Chúng tôi không cho phép liên kết bởi Người sáng tạo. -- Đối với các tác phẩm tổng hợp hoặc phối lại, "người sáng tạo" có thể cần mô tả. Ví dụ: sách "GoalKicker" được ghi là "Được tổng hợp từ tài liệu StackOverflow" +- Đối với các tác phẩm tổng hợp hoặc phối lại, "người sáng tạo" có thể cần mô tả. Ví dụ: sách "GoalKicker" được ghi là "`Được tổng hợp từ tài liệu StackOverflow`" (bằng tiếng anh: "`Compiled from StackOverflow documentation`"). + ##### Nền Tảng và Ghi Chú Truy Cập - Các khóa học. Đặc biệt đối với danh sách khóa học của chúng tôi, nền tảng là một phần quan trọng của mô tả tài liệu. Điều này là do các khóa học nền tảng có khả năng chi trả và mô hình truy cập khác nhau. Mặc dù chúng tôi thường không liệt kê một cuốn sách yêu cầu đăng ký, nhưng nhiều nền tảng khóa học có khả năng không hoạt động nếu không có một số loại tài khoản. Các nền tảng khóa học ví dụ bao gồm Coursera, EdX, Udacity và Udemy. Khi một khóa học phụ thuộc vào một nền tảng, tên nền tảng phải được liệt kê trong ngoặc đơn. -- YouTube. Chúng tôi có nhiều khóa học bao gồm các danh sách phát trên YouTube. Chúng tôi không cho rằng Youtube như một nền tảng, chúng tôi cố gắng liệt kê người sáng tạo nội dung trên YouTube, thường là một nền tảng phụ. +- YouTube. Chúng tôi có nhiều khóa học bao gồm các danh sách phát trên YouTube. Chúng tôi không cho rằng YouTube như một nền tảng, chúng tôi cố gắng liệt kê người sáng tạo nội dung trên YouTube, thường là một nền tảng phụ. - Video trên YouTube. Chúng tôi thường không có các liên kết đến các video YouTube riêng lẻ trừ khi chúng dài hơn một giờ và có cấu trúc giống như một khóa học hoặc một hướng dẫn. -- Leanpub. Leanpub lưu trữ sách với nhiều mô hình truy cập. Đôi khi một cuốn sách có thể được đọc mà không cần đăng ký; đôi khi một cuốn sách yêu cầu tài khoản Leanpub để được truy cập miễn phí. Do chất lượng của sách và sự hỗn hợp và tính linh hoạt của các mô hình truy cập Leanpub, chúng tôi cho phép liệt kê mô hình sau cùng với ghi chú truy cập *(yêu cầu tài khoản Leanpub hoặc email hợp lệ)* +- Leanpub. Leanpub lưu trữ sách với nhiều mô hình truy cập. Đôi khi một cuốn sách có thể được đọc mà không cần đăng ký; đôi khi một cuốn sách yêu cầu tài khoản Leanpub để được truy cập miễn phí. Do chất lượng của sách và sự hỗn hợp và tính linh hoạt của các mô hình truy cập Leanpub, chúng tôi cho phép liệt kê mô hình sau cùng với ghi chú truy cập `*(yêu cầu tài khoản Leanpub hoặc email hợp lệ)*`. + #### Thể Loại Quy tắc đầu tiên để quyết định tài liệu thuộc danh sách nào là xem tài liệu đó mô tả thế nào. Nếu nó tự gọi nó là một cuốn sách, thì có lẽ nó là một cuốn sách. + ##### Các Thể Loại chúng tôi không liệt kê Vì Internet rất rộng lớn, chúng tôi không đưa chúng vào danh sách của mình: @@ -175,7 +197,7 @@ Vì Internet rất rộng lớn, chúng tôi không đưa chúng vào danh sách - blogs - bài đăng trên blog - bài viết -- các trang web (ngoại trừ những nơi lưu trữ RẤT NHIỀU tài liệu mà chúng tôi liệt kê.) +- các trang web (ngoại trừ những nơi lưu trữ RẤT NHIỀU tài liệu mà chúng tôi liệt kê). - video không phải là khóa học hoặc video truyền hình. - các chương của cuốn sách - các ví dụ khó từ sách @@ -189,7 +211,7 @@ Danh sách của chúng tôi không nghiêm ngặt về những loại trừ nà Chúng tôi không quá cầu kỳ về sách. Dưới đây là một số thuộc tính biểu thị rằng nguồn tài liệu là sách: -- nó có một ISBN +- nó có một ISBN (International Standard Book Number) - nó có một Mục lục - một phiên bản đã tải xuống, đặc biệt là ePub - nó có các tái bản @@ -214,13 +236,13 @@ Nếu bạn có thể in nó ra và giữ lại bản chất của nó, thì đ ### Tự động hóa -- Việc thực thi nguyên tắc định dạng được tự động hóa qua [Github Actions](https://docs.github.com/en/actions) sử dụng [fpb-lint](https://github.com/vhf/free-programming-books-lint) (xem file [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Việc thực thi nguyên tắc định dạng được tự động hóa qua [GitHub Actions](https://docs.github.com/en/actions) sử dụng [fpb-lint](https://github.com/vhf/free-programming-books-lint) (xem file [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - Sử dụng xác thực liên kết [awesome_bot](https://github.com/dkhamsing/awesome_bot) - Để kích hoạt xác thực liên kết, hãy push một commit bao gồm một commit message chứa `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-vi.md + ``` - Bạn có thể chỉ định nhiều tệp để kiểm tra, sử dụng một khoảng trắng duy nhất để tách từng mục nhập. -- Nếu bạn chỉ định nhiều hơn một tệp, kết quả của việc xây dựng sẽ dựa trên kết quả của tệp cuối cùng được kiểm tra. Bạn nên biết rằng bạn có thể nhận được bản xây dựng thành công, vì vậy hãy đảm bảo kiểm tra log ở cuối pull request bằng cách nhấp vào "Show all checks" -> "Details". +- Nếu bạn chỉ định nhiều hơn một tệp, kết quả của việc xây dựng sẽ dựa trên kết quả của tệp cuối cùng được kiểm tra. Bạn nên biết rằng bạn có thể nhận được bản xây dựng thành công, vì vậy hãy đảm bảo kiểm tra log ở cuối Pull Request bằng cách nhấp vào "Show all checks" -> "Details". diff --git a/docs/CONTRIBUTING-zh.md b/docs/CONTRIBUTING-zh.md index 9e9b007bf8ee5..7521efd239ed6 100644 --- a/docs/CONTRIBUTING-zh.md +++ b/docs/CONTRIBUTING-zh.md @@ -14,19 +14,21 @@ ## 概要 1. "一个可以轻易下载一本书的链接" 并不代表它指向的就是 *免费* 书籍。 请只提供免费内容。 确信你所提供的书籍是免费的。我们不接受指向*需要*工作电子邮件地址才能获取书籍的页面的链接，但我们欢迎有需求它们的列表。 + 2. 你不需要会 Git：如果你发现了一些有趣的东西 *尚未出现在本仓库* 中，请开一个[Issue](https://github.com/EbookFoundation/free-programming-books/issues)进行主题讨论。 - * 如果你已经知晓Git，请Fork本仓库并提交PR。 + * 如果你已经知晓Git，请Fork本仓库并提交Pull Request (PR)。 + 3. 这里有5种列表，请选择正确的一个： * *Books* ：PDF、HTML、ePub、基于一个 gitbook.io的站点、一个Git仓库等等。 * *Courses* ：课程是一种学习材料，而不是一本书 [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/)。 - * *Interactive Tutorials* ：一个交互式网站，它允许用户输入代码或命令并对结果进行评估。例如：[Try Haskell](http://tryhaskell.org)，[Try Github](http://try.github.io)。 + * *Interactive Tutorials* ：一个交互式网站，它允许用户输入代码或命令并对结果进行评估。例如：[Try Haskell](http://tryhaskell.org)，[Try GitHub](http://try.github.io)。 * *Podcasts and Screencasts* ：播客和视频。 * *Problem Sets & Competitive Programming* ：一个网站或软件，让你通过解决简单或复杂的问题来评估你的编程技能，有或没有代码审查，有或没有与其他用户对比结果。 4. 确保遵循下面的[基本准则](#基本准则)，并遵循本仓库文件的[Markdown规定格式](#规定格式)。 -5. Github Actions 将运行测试，以确保你的列表是 **按字母顺序排列** 的，并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。 +5. GitHub Actions 将运行测试，以确保你的列表是 **按字母顺序排列** 的，并 **遵循格式化规则**。请 **确保** 你的更改通过了该测试。 ### 基本准则 @@ -42,17 +44,17 @@ * 不要提供短链接 * 优先选择使用 "current" 链接代替有 "version" 链接：使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。 * 如果一个链接存在过期的证书/自签名证书/SSL问题的任何其他类型： - 1. *replace it* ：如果可能的话，将其 *替换* 为对应的`http`(因为在移动设备上接受异常可能比较复杂)。 - 2. *leave it* ：如果没有http版本，但仍然可以通过https访问链接，则在浏览器中添加异常或忽略警告。 - 3. *remove it* ：上述以外删除掉它。 + 1. *replace it* ：如果可能的话，将其 *替换* 为对应的`http`(因为在移动设备上接受异常可能比较复杂)。 + 2. *leave it* ：如果没有`http`版本，但仍然可以通过`https`访问链接，则在浏览器中添加异常或忽略警告。 + 3. *remove it* ：上述以外删除掉它。 * 如果一个链接以多种格式存在，请添加一个单独的链接，并注明每种格式。 * 如果一个资源存在于Internet上的不同位置 * 使用最权威来源的链接(意思是原始作者的网站比编辑的网站好，比第三方网站好)。 * 如果它们链接到不同的版本，你认为这些版本差异很大，值得保留，那么添加一个单独的链接，并对每个版本做一个说明(参见[Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353)有助于格式化问题的讨论)。 * 相较一个比较大的提交，我们更倾向于原子提交(通过添加/删除/修改进行一次提交)。在提交PR之前没有必要压缩你的提交。(我们永远不会执行这个规则，因为这只是维护人员的方便)。 * 如果一本书比较旧，请在书名中注明出版日期。 -* 包含作者的名字或适当的名字。中文版本可以用 “等” 缩短作者列表。 -* 如果一本书还没有完成，并且仍在编写中，则需添加 “编写中” 符号，参见[下文](#in_process)所述。 +* 包含作者的名字或适当的名字。中文版本可以用 “`等`” (“`et al.`”) 缩短作者列表。 +* 如果一本书还没有完成，并且仍在编写中，则需添加 “`in process`” 符号，参见[下文](#in_process)所述。 * 如果在开始下载之前需要电子邮件地址或帐户设置，请在括号中添加合适的语言描述，例如：`(*需要*电子邮件，但不是必须的)`。 @@ -62,18 +64,16 @@ * 所有的列表都以索引开始。它的作用是列出并链接所有的sections(章节/段落)或subsections(子段落/子章节)。务必遵循字母顺序排列。 * Sections(章节/段落)使用3级标题(`###`)，subsections(子段落/子章节)使用4级标题 (`####`)。 - -#### 整体思想为： +整体思想为： * `2` ：新添加的Section与末尾链接间必须留有`2`个空行 * `1` ：标题和第一个链接之间必须留有`1`个空行的空行 * `0` ：任何两个链接之间不能留有任何空行 * `1` ：每个`.md`文件末尾必须留有`1`个空行 +举例： -#### 举例： - -``` +```text [...] * [一本很有用的书](http://example.com/example.html) (空行) @@ -86,66 +86,65 @@ * 在 `]` 和 `(` 之间不要留有空格： -``` -错误：* [一本很有用的书] (http://example.com/book.html) -正确：* [一本很有用的书](http://example.com/book.html) -``` + ```text + 错误：* [一本很有用的书] (http://example.com/book.html) + 正确：* [一本很有用的书](http://example.com/book.html) + ``` * 如果包括作者，请使用' - '(由单个空格(英文半角)包围的破折号)： -``` -错误：* [一本很有用的书](http://example.com/book.html)- 张显宗 -正确：* [一本很有用的书](http://example.com/book.html) - 张显宗 -``` + ```text + 错误：* [一本很有用的书](http://example.com/book.html)- 张显宗 + 正确：* [一本很有用的书](http://example.com/book.html) - 张显宗 + ``` * 在链接和电子书格式之间放一个空格： -``` -错误：* [一本很有用的书](https://example.org/book.pdf)(PDF) -正确：* [一本很有用的书](https://example.org/book.pdf) (PDF) -``` + ```text + 错误：* [一本很有用的书](https://example.org/book.pdf)(PDF) + 正确：* [一本很有用的书](https://example.org/book.pdf) (PDF) + ``` * 如需备注或注解，请使用英文半角括号`( )`： -``` -错误：* [一本很有用的书](https://example.org/book.pdf) （繁体中文） -正确：* [一本很有用的书](https://example.org/book.pdf) (繁体中文) -``` + ```text + 错误：* [一本很有用的书](https://example.org/book.pdf) （繁体中文） + 正确：* [一本很有用的书](https://example.org/book.pdf) (繁体中文) + ``` * 作者在电子书格式之前： -``` -错误：* [一本很有用的书](https://example.org/book.pdf)- (PDF) 张显宗 -正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗 (PDF) -``` + ```text + 错误：* [一本很有用的书](https://example.org/book.pdf)- (PDF) 张显宗 + 正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗 (PDF) + ``` * 多重格式： -``` -错误：* [一本很有用的书](http://example.com/)- 张显宗 (HTML) -错误：* [一本很有用的书](https://downloads.example.org/book.html)- 张显宗 (download site) -正确：* [一本很有用的书](http://example.com/) - 张显宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + 错误：* [一本很有用的书](http://example.com/)- 张显宗 (HTML) + 错误：* [一本很有用的书](https://downloads.example.org/book.html)- 张显宗 (download site) + 正确：* [一本很有用的书](http://example.com/) - 张显宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` * 多作者，多译者时，请使用中文 `、` 进行分隔，在译者名字后请使用英文半角括号包围的 `(翻译)`，可以用 “等” 缩短作者列表： -``` -错误：* [一本很有用的书](https://example.org/book.pdf) - 张显宗，岳绮罗 -正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗(翻译) -正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗、顾玄武、出尘子 等 -``` + ```text + 错误：* [一本很有用的书](https://example.org/book.pdf) - 张显宗，岳绮罗 + 正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗(翻译) + 正确：* [一本很有用的书](https://example.org/book.pdf) - 张显宗、岳绮罗、顾玄武、出尘子 等 + ``` * 在旧书的标题中包括出版年份： -``` -错误：* [一本很有用的书](https://example.org/book.html) - 张显宗 - 1970 -正确：* [一本很有用的书 (1970)](https://example.org/book.html) - 张显宗 -``` + ```text + 错误：* [一本很有用的书](https://example.org/book.html) - 张显宗 - 1970 + 正确：* [一本很有用的书 (1970)](https://example.org/book.html) - 张显宗 + ``` - -* 编写(翻译)中的书籍： +* 编写(翻译)中的书籍： -``` -正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *编写中*) -正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *翻译中*) -``` + ```text + 正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *编写中*) + 正确：* [马上出版的一本书](http://example.com/book2.html) - 张显宗 (HTML) (:construction: *翻译中*) + ``` diff --git a/docs/CONTRIBUTING-zh_TW.md b/docs/CONTRIBUTING-zh_TW.md index 22130c3cba551..b234920d24ad3 100644 --- a/docs/CONTRIBUTING-zh_TW.md +++ b/docs/CONTRIBUTING-zh_TW.md @@ -16,19 +16,19 @@ 1. "一個可以輕易下載一本書的連結" 並不代表它導向的就是 *免費* 書籍。 請只提供免費內容。 確信你所提供的書籍是免費的。我們不接受導向 *需要* 工作電子郵件地址才能獲取書籍頁面的連結，但我們歡迎有需求這些連結的列表。 2. 你不需要會 Git：如果你發現了一些有趣的東西 *尚未出現在此 repo* 中，請開一個 [Issue](https://github.com/EbookFoundation/free-programming-books/issues) 進行主題討論。 - * 如果你已經知道 Git，請 Fork 此 repo 並提交 PR。 + * 如果你已經知道 Git，請 Fork 此 repo 並提交 Pull Request (PR)。 3. 這裡有五種列表，請選擇正確的一項： * *Books* ：PDF、HTML、ePub、基於 gitbook.io 的網站、Git 的 repo 等。 * *Courses* ：課程是一種學習素材，而不是一本書 [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/)。 - * *Interactive Tutorials* ：一個互動式網站，允許用戶輸入程式碼或指令並執行結果。例如：[Try Haskell](http://tryhaskell.org)，[Try Github](http://try.github.io)。 + * *Interactive Tutorials* ：一個互動式網站，允許用戶輸入程式碼或指令並執行結果。例如：[Try Haskell](http://tryhaskell.org)，[Try GitHub](http://try.github.io)。 * *Podcasts and Screencasts* ：Podcast 和影音。 * *Problem Sets & Competitive Programming* ：一個網站或軟體，讓你透過解決簡單或複雜的問題來評估你的程式技能，可能有程式碼檢查，或與其他用戶比對结果。 4. 確保遵循下方的 [基本準則](#基本準則)，並遵循此 repo 文件的 [Markdown 規定格式](#規定格式)。 -5. Github Actions 將運行測試，以確保你的列表是 **按字母顺序排列** 的，並 **遵循格式化規則**。請 **確保** 你的更改通過該測試。 +5. GitHub Actions 將運行測試，以確保你的列表是 **按字母顺序排列** 的，並 **遵循格式化規則**。請 **確保** 你的更改通過該測試。 ### 基本準則 @@ -44,17 +44,17 @@ * 不要提供短連結 * 優先選擇使用 "current" 連結代替有 "version" 連結：使用 `http://example.com/dir/book/current/` 比使用 `http://example.com/dir/book/v1.0.0/index.html` 更好。 * 如果一個連結存在過期的證書/自簽名證書/SSL問題的任何其他類型： - 1. *replace it* ：如果可能的話，將其 *替換* 為對應的 `http` (因為在移動設備上接受異常可能比較複雜)。 - 2. *leave it* ：如果沒有http版本，但仍然可以通過https造訪連結，則在瀏覽器中添加異常或忽略警告。 - 3. *remove it* ：上述狀況以外則刪除掉它。 + 1. *replace it* ：如果可能的話，將其 *替換* 為對應的 `http` (因為在移動設備上接受異常可能比較複雜)。 + 2. *leave it* ：如果沒有`http`版本，但仍然可以通過`https`造訪連結，則在瀏覽器中添加異常或忽略警告。 + 3. *remove it* ：上述狀況以外則刪除掉它。 * 如果一個連結以多種格式存在，請添加一個單獨的連結，並註明每種格式。 * 如果一個資源存在於Internet上的不同位置 * 使用最權威來源的連結(意思是原始作者的網站比編輯的網站好，比第三方網站好)。 * 如果它們連結到不同的版本，你認為這些版本差異很大，值得保留，那麼添加一個單獨的連結，並對每個版本做說明(參考 [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) 有助於格式化問題的討論)。 * 相較一個比較大的提交，我們更傾向於原子提交(通過添加/删除/修改進行一次提交)。在提交PR之前没有必要壓縮你的提交。(為了維護人員的方便，我們永遠不會執行這個規則)。 * 如果一本書比較舊，請在書名中註明出版日期。 -* 包含作者的名字或適當的名字。中文版本可以用 “等” 縮短作者列表。 -* 如果一本書還没有完成，並且仍在編寫中，則需添加 “編寫中” 符號，參考 [下文](#in_process) 所述。 +* 包含作者的名字或適當的名字。中文版本可以用 “`等`” (“`et al.`”) 縮短作者列表。 +* 如果一本書還没有完成，並且仍在編寫中，則需添加 “`in process`” 符號，參考 [下文](#in_process) 所述。 * 如果在開始下載之前需要電子郵件地址或帳户設置，請在括號中添加合適的語言描述，例如：`(*需要* 電子郵件，但不是必需的)`。 @@ -64,18 +64,16 @@ * 所有的列表都以索引開始。它的作用是列出並連結所有的 sections (章節/段落)或 subsections (子段落/子章節)。務必遵循字母順序排列。 * Sections (章節/段落)使用3級標題(`###`)，subsections (子段落/子章節)使用4級標題 (`####`)。 - -#### 整體思維為： +整體思維為： * `2` ：新添加的 Section 與末尾連結間必需留有 `2` 個空行 * `1` ：標題和第一個連結之間必需留有 `1` 個空行的空行 * `0` ：任何兩個連結之間不能留有任何空行 * `1` ：每個 `.md` 文件末尾必需留有 `1` 個空行 +舉例： -#### 舉例： - -``` +```text [...] * [一本很有用的書](http://example.com/example.html) (空行) @@ -88,78 +86,79 @@ * 在 `]` 和 `(` 之間不要留有空格： -``` -錯誤：* [一本很有用的書] (http://example.com/book.html) -正確：* [一本很有用的書](http://example.com/book.html) -``` + ```text + 錯誤：* [一本很有用的書] (http://example.com/book.html) + 正確：* [一本很有用的書](http://example.com/book.html) + ``` * 如果包括作者，請使用' - '(由單個空格(英文半型)包圍的破折號)： -``` -錯誤：* [一本很有用的書](http://example.com/book.html)- 張顯宗 -正確：* [一本很有用的書](http://example.com/book.html) - 張顯宗 -``` + ```text + 錯誤：* [一本很有用的書](http://example.com/book.html)- 張顯宗 + 正確：* [一本很有用的書](http://example.com/book.html) - 張顯宗 + ``` * 在連結和電子書格式之間放一個空格： -``` -錯誤：* [一本很有用的書](https://example.org/book.pdf)(PDF) -正確：* [一本很有用的書](https://example.org/book.pdf) (PDF) -``` + ```text + 錯誤：* [一本很有用的書](https://example.org/book.pdf)(PDF) + 正確：* [一本很有用的書](https://example.org/book.pdf) (PDF) + ``` * 如需備注或注解，請使用英文半型括號`( )`： -``` -錯誤：* [一本很有用的書](https://example.org/book.pdf) （繁體中文） -正確：* [一本很有用的書](https://example.org/book.pdf) (繁體中文) -``` + ```text + 錯誤：* [一本很有用的書](https://example.org/book.pdf) （繁體中文） + 正確：* [一本很有用的書](https://example.org/book.pdf) (繁體中文) + ``` * 作者在電子書格式之前： -``` -錯誤：* [一本很有用的書](https://example.org/book.pdf)- (PDF) 張顯宗 -正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗 (PDF) -``` + ```text + 錯誤：* [一本很有用的書](https://example.org/book.pdf)- (PDF) 張顯宗 + 正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗 (PDF) + ``` * 多重格式： -``` -錯誤：* [一本很有用的書](http://example.com/)- 張顯宗 (HTML) -錯誤：* [一本很有用的書](https://downloads.example.org/book.html)- 張顯宗 (download site) -正確：* [一本很有用的書](http://example.com/) - 張顯宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + 錯誤：* [一本很有用的書](http://example.com/)- 張顯宗 (HTML) + 錯誤：* [一本很有用的書](https://downloads.example.org/book.html)- 張顯宗 (download site) + 正確：* [一本很有用的書](http://example.com/) - 張顯宗 (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` * 多作者，多譯者時，請使用中文 `、` 進行分隔，在譯者名字後請使用英文半型括號包圍的 `(翻譯)`，可以用 “等” 縮短作者列表： -``` -錯誤：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗，岳綺羅 -正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅(翻譯) -正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅、顧玄武、出塵子 等 -``` + ```text + 錯誤：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗，岳綺羅 + 正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅(翻譯) + 正確：* [一本很有用的書](https://example.org/book.pdf) - 張顯宗、岳綺羅、顧玄武、出塵子 等 + ``` * 在舊書的標題中包括出版年份： -``` -錯誤：* [一本很有用的書](https://example.org/book.html) - 張顯宗 - 1970 -正確：* [一本很有用的書 (1970)](https://example.org/book.html) - 張顯宗 -``` + ```text + 錯誤：* [一本很有用的書](https://example.org/book.html) - 張顯宗 - 1970 + 正確：* [一本很有用的書 (1970)](https://example.org/book.html) - 張顯宗 + ``` - -* 編寫(翻譯)中的書籍： +* 編寫(翻譯)中的書籍： + + ```text + 正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) (:construction: *編寫中*) + 正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) (:construction: *翻譯中*) + ``` -``` -正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) (:construction: *編寫中*) -正確：* [即將出版的一本書](http://example.com/book2.html) - 張顯宗 (HTML) (:construction: *翻譯中*) -``` ### 自動化測試 -- 規定格式驗證是由 [Github Actions](https://docs.github.com/en/actions) 自動化進行，使用 [fpb-lint](https://github.com/vhf/free-programming-books-lint) 套件 (參閱 [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml))。 + +- 規定格式驗證是由 [GitHub Actions](https://docs.github.com/en/actions) 自動化進行，使用 [fpb-lint](https://github.com/vhf/free-programming-books-lint) 套件 (參閱 [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml))。 - 使用 [awesome_bot](https://github.com/dkhamsing/awesome_bot) 進行連結驗證。 - 可以藉由提交一個內容包含`check_urls=file_to_check`來觸發連結驗證: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-zh.md + ``` - 您可以以一個空白區隔出想要進行驗證的檔案名稱來一次驗證多個檔案。 -- 如果您一次驗證多個檔案，自動化測試的結果會是基於最後一個驗證的檔案。您的測試可能會因此通過，因此請詳加確認測試日誌。可以在 pull request 結果中點選"Show all checks" -> "Details" 來查看。 +- 如果您一次驗證多個檔案，自動化測試的結果會是基於最後一個驗證的檔案。您的測試可能會因此通過，因此請詳加確認測試日誌。可以在 Pull Request 結果中點選"Show all checks" -> "Details" 來查看。 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7811f79c1a774..e0eccbcecddd2 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,59 +1,72 @@ *[Read this in other languages](../README.md#translations)* + ## Contributor License Agreement -By contributing you agree to the [LICENSE](https://github.com/EbookFoundation/free-programming-books/blob/main/LICENSE) of this repository. + +By contributing you agree to the [LICENSE](../LICENSE) of this repository. + ## Contributor Code of Conduct + By contributing you agree to respect the [Code of Conduct](CODE_OF_CONDUCT.md) of this repository. ([translations](../README.md#translations)) + ## In a nutshell + 1. "A link to easily download a book" is not always a link to a *free* book. Please only contribute free content. Make sure it's free. We do not accept links to pages that *require* working email addresses to obtain books, but we welcome listings that request them. + 2. You don't have to know Git: if you found something of interest which is *not already in this repo*, please open an [Issue](https://github.com/EbookFoundation/free-programming-books/issues) with your links propositions. - - If you know Git, please Fork the repo and send pull requests. + - If you know Git, please Fork the repo and send Pull Requests (PR). + 3. We have 5 kinds of lists. Choose the right one: - *Books* : PDF, HTML, ePub, a gitbook.io based site, a Git repo, etc. - *Courses* : A course is a learning material which is not a book. [This is a course](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/). - - *Interactive Tutorials* : An interactive website which lets the user type code or commands and evaluates the result (by "evaluate" we don't mean "grade"). e.g.: [Try Haskell](http://tryhaskell.org), [Try Github](http://try.github.io). + - *Interactive Tutorials* : An interactive website which lets the user type code or commands and evaluates the result (by "evaluate" we don't mean "grade"). e.g.: [Try Haskell](http://tryhaskell.org), [Try GitHub](http://try.github.io). - *Podcasts and Screencasts* : Podcasts and screencasts. - *Problem Sets & Competitive Programming* : A website or software which lets you assess your programming skills by solving simple or complex problems, with or without code review, with or without comparing the results with other users. 4. Make sure to follow the [guidelines below](#guidelines) and respect the [Markdown formatting](#formatting) of the files. -5. GitHub Actions will run tests to make sure your lists are alphabetized and formatting rules are followed. Be sure to check that your changes pass the tests. +5. GitHub Actions will run tests to **make sure your lists are alphabetized** and **formatting rules are followed**. **Be sure** to check that your changes pass the tests. + ### Guidelines + - make sure a book is free. Double-check if needed. It helps the admins if you comment in the PR as to why you think the book is free. - we don't accept files hosted on Google Drive, Dropbox, Mega, Scribd, Issuu and other similar file upload platforms - insert your links in alphabetical order. If you see a misplaced link, please reorder it and submit a PR - use the link with the most authoritative source (meaning the author's website is better than the editor's website, which is better than a third party website) - + no file hosting services (this includes (but is not limited to) Dropbox and Google Drive links) + - no file hosting services (this includes (but is not limited to) Dropbox and Google Drive links) - always prefer a `https` link over a `http` one -- as long as they are on the same domain and serve the same content - on root domains, strip the trailing slash: `http://example.com` instead of `http://example.com/` - always prefer the shortest link: `http://example.com/dir/` is better than `http://example.com/dir/index.html` - + no URL shortener links + - no URL shortener links - usually prefer the "current" link over the "version" one: `http://example.com/dir/book/current/` is better than `http://example.com/dir/book/v1.0.0/index.html` - if a link has an expired certificate/self-signed certificate/SSL issue of any other kind: - 1. *replace it* with its `http` counterpart if possible (because accepting exceptions can be complicated on mobile devices). - 2. *leave it* if no `http` version is available but the link is still accessible through `https` by adding an exception to the browser or ignoring the warning. - 3. *remove it* otherwise. + 1. *replace it* with its `http` counterpart if possible (because accepting exceptions can be complicated on mobile devices). + 2. *leave it* if no `http` version is available but the link is still accessible through `https` by adding an exception to the browser or ignoring the warning. + 3. *remove it* otherwise. - if a link exists in multiple format, add a separate link with a note about each format - if a resource exists at different places on the Internet - + use the link with the most authoritative source (meaning author's website is better than editor's website is better than third party website) - + if they link to different editions, and you judge these editions are different enough to be worth keeping them, add a separate link with a note about each edition (see [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) to contribute to the discussion on formatting.) + - use the link with the most authoritative source (meaning author's website is better than editor's website is better than third party website) + - if they link to different editions, and you judge these editions are different enough to be worth keeping them, add a separate link with a note about each edition (see [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353) to contribute to the discussion on formatting). - prefer atomic commits (one commit by addition/deletion/modification) over bigger commits. No need to squash your commits before submitting a PR. (We will never enforce this rule as it's just a matter of convenience for the maintainers) - if the book is older, include the publication date with the title. -- include the author name or names where appropriate. You can shorten author lists with "et al." -- if the book is not finished, and is still being worked on, add the "in process" notation, as described [below.](#in_process) -- if a resource is restored using the Internet Archive's Wayback Machine (or similar), add the "archived" notation, as described [below](#archived). The best versions to use are recent and complete. -- if an email address or account setup is requested before download is enabled, add language-appropriate notes in parentheses, e.g.: `(email address *requested*, not required)` +- include the author name or names where appropriate. You can shorten author lists with "`et al.`". +- if the book is not finished, and is still being worked on, add the "`in process`" notation, as described [below](#in_process). +- if a resource is restored using the [*Internet Archive's Wayback Machine*](https://web.archive.org) (or similar), add the "`archived`" notation, as described [below](#archived). The best versions to use are recent and complete. +- if an email address or account setup is requested before download is enabled, add language-appropriate notes in parentheses, e.g.: `(email address *requested*, not required)`. + ### Formatting + - All lists are `.md` files. Try to learn [Markdown](https://guides.github.com/features/mastering-markdown/) syntax. It's simple! - All the lists start with an Index. The idea is to list and link all sections and subsections there. Keep it in alphabetical order. - Sections are using level 3 headings (`###`), and subsections are level 4 headings (`####`). The idea is to have: + - `2` empty lines between last link and new section. - `1` empty line between heading & first link of its section. - `0` empty line between two links. @@ -61,111 +74,119 @@ The idea is to have: Example: - [...] - * [An Awesome Book](http://example.com/example.html) - (blank line) - (blank line) - ### Example - (blank line) - * [Another Awesome Book](http://example.com/book.html) - * [Some Other Book](http://example.com/other.html) +```text +[...] +* [An Awesome Book](http://example.com/example.html) + (blank line) + (blank line) +### Example + (blank line) +* [Another Awesome Book](http://example.com/book.html) +* [Some Other Book](http://example.com/other.html) +``` - Don't put spaces between `]` and `(`: -``` -BAD : * [Another Awesome Book] (http://example.com/book.html) -GOOD: * [Another Awesome Book](http://example.com/book.html) -``` + ```text + BAD : * [Another Awesome Book] (http://example.com/book.html) + GOOD: * [Another Awesome Book](http://example.com/book.html) + ``` - If you include the author, use ` - ` (a dash surrounded by single spaces): -``` -BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe -GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe -``` + ```text + BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe + GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe + ``` - Put a single space between the link and its format: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF) + ``` - Author comes before format: -``` -BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe -GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe + GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) + ``` - Multiple formats: -``` -BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) -BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) -GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) -``` + ```text + BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) + BAD : * [Another Awesome Book](https://downloads.example.org/book.html)- John Doe (download site) + GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html) + ``` - Include publication year in title for older books: -``` -BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 -GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe -``` + ```text + BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 + GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe + ``` - -- In-process books: +- In-process books: -``` -GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) -``` + ```text + GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*) + ``` - -- Archived link: +- Archived link: + + ```text + GOOD: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* + ``` -``` -GOOD: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)* -``` ### Notes While the basics are relatively simple, there is a great diversity in the resources we list. Here are some notes on how we deal with this diversity. + #### Metadata Our lists provide a minimal set of metadata: titles, URLs, creators, platforms, and access notes. + ##### Titles - No invented titles. We try to take titles from the resources themselves; contributors are admonished not to invent titles or use them editorially if this can be avoided. An exception is for older works; if they are primarily of historical interest, a year in parentheses appended to the title helps users know if they are of interest. - No ALLCAPS titles. Usually title case is appropriate, but when doubt use the capitalization from the source + ##### URLs - We don't permit shortened URLs. - Tracking codes must be removed from the URL. - International URLs should be escaped. Browser bars typically render these to Unicode, but use copy and paste, please. -- Secure (https) URLs are always preferred over non-secure (http) urls where https has been implemented. +- Secure (`https`) URLs are always preferred over non-secure (`http`) urls where HTTPS has been implemented. - We don't like URLs that point to webpages that don't host the listed resource, but instead point elsewhere. + ##### Creators - We want to credit the creators of free resources where appropriate, including translators! - For translated works the original author should be credited. - We do not permit links for Creators. -- For compilation or remixed works, the "creator" may need a description. For example, "GoalKicker" or "RIP Tutorial" books are credited as "Compiled from StackOverflow documentation" +- For compilation or remixed works, the "creator" may need a description. For example, "GoalKicker" or "RIP Tutorial" books are credited as "`Compiled from StackOverflow documentation`". + ##### Platforms and Access Notes - Courses. Especially for our course lists, the platform is an important part of the resource description. This is because course platforms have different affordances and access models. While we usually won't list a book that requires a registration, many course platforms have affordances that don't work without some sort of account. Example course platforms include Coursera, EdX, Udacity, and Udemy. When a course depends on a platform, the platform name should be listed in parentheses. -- YouTube. We have many courses which consist of YouTube playlists. We do not list Youtube as a platform, we try to list the Youtube creator, which is often a sub-platform. +- YouTube. We have many courses which consist of YouTube playlists. We do not list YouTube as a platform, we try to list the YouTube creator, which is often a sub-platform. - YouTube videos. We usually don't link to individual YouTube videos unless they are more than an hour long and are structured like a course or a tutorial. -- Leanpub. Leanpub hosts books with a variety of access models. Sometimes a book can be read without registration; sometimes a book requires a Leanpub account for free access. Given quality of the books and the mixture and fluidity of Leanpub access models, we permit listing of the latter with the access note *(Leanpub account or valid email requested)* +- Leanpub. Leanpub hosts books with a variety of access models. Sometimes a book can be read without registration; sometimes a book requires a Leanpub account for free access. Given quality of the books and the mixture and fluidity of Leanpub access models, we permit listing of the latter with the access note `*(Leanpub account or valid email requested)*`. + #### Genres The first rule in deciding which list a resource belongs in is to see how the resource describes itself. If it calls itself a book, then maybe it's a book. + ##### Genres we don't list Because the Internet is vast, we don't include in our lists: @@ -173,7 +194,7 @@ Because the Internet is vast, we don't include in our lists: - blogs - blog posts - articles -- websites (except for those that host LOTS of items that we list.) +- websites (except for those that host LOTS of items that we list). - videos that aren't courses or screencasts. - book chapters - teaser samples from books @@ -212,13 +233,13 @@ If you can print it out and retain its essence, it's not an Interactive Tutorial ### Automation -- Formatting rules enforcement is automated via [GitHub Actions](https://github.com/features/actions) using [fpb-lint](https://github.com/vhf/free-programming-books-lint) (see [.github/workflows/fpb-lint.yml](.github/workflows/fpb-lint.yml)) +- Formatting rules enforcement is automated via [GitHub Actions](https://github.com/features/actions) using [fpb-lint](https://github.com/vhf/free-programming-books-lint) (see [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml)) - URL validation uses [awesome_bot](https://github.com/dkhamsing/awesome_bot) - To trigger URL validation, push a commit that includes a commit message containing `check_urls=file_to_check`: -``` -check_urls=free-programming-books.md free-programming-books-en.md -``` + ```properties + check_urls=free-programming-books.md free-programming-books-en.md + ``` - You may specify more than one file to check, using a single space to separate each entry. -- If you specify more than one file, results of the build are based on the result of the last file checked. You should be aware that you may get passing green builds due to this so be sure to inspect the build log at the end of the pull request by clicking on "Show all checks" -> "Details". +- If you specify more than one file, results of the build are based on the result of the last file checked. You should be aware that you may get passing green builds due to this so be sure to inspect the build log at the end of the Pull Request by clicking on "Show all checks" -> "Details".