From 5172a3a3dc0f94d22669bd46cdbe3b4b405942d3 Mon Sep 17 00:00:00 2001 From: Leah Rowe Date: Tue, 6 Jun 2017 21:37:43 +0100 Subject: simplify the patching instructions at git.md --- www/git.md | 98 ++++++++++++++------------------------------------------------ 1 file changed, 21 insertions(+), 77 deletions(-) (limited to 'www/git.md') diff --git a/www/git.md b/www/git.md index 8c17ea54..ab63f042 100644 --- a/www/git.md +++ b/www/git.md @@ -3,10 +3,6 @@ title: Information about sending patches for review x-toc-enable: true ... -Useful information, related to Libreboot development, including links to the -Git repositories where development is done. Libreboot development is discussed -on the [IRC channel](https://webchat.freenode.net/?channels=libreboot). - Download Libreboot from the Git repository here: **git clone https://notabug.org/libreboot/libreboot.git** @@ -14,49 +10,23 @@ Download Libreboot from the Git repository here: Editing the website and documentation, wiki-style ------------------------------------------------- -The entire website on libreboot.org, including all of the Libreboot -documentation, is hosted in the Git repository. The pages are written in -Markdown, which is an easy-to-use markup language similar to the one used -when, for instance, editing pages on WikiPedia or a MediaWiki-based website. - -Just download Libreboot's Git repository, make changes to the website under -the ***www*** directory. Changes to the documentation section are made under -the ***docs*** directory. Once you've made your changes, you can submit them -for inclusion live on libreboot.org, using the instructions on the rest of this -page. - -***You can use any standard text editor to edit and improve the entire -Libreboot website. E.g. Vim, GNU Emacs, GNU Nano, Gedit or whatever you -prefer to use.*** - -We currently have a shortage of people who possess the skill to write and -maintain good documentation for Libreboot, so we welcome any and all -contributions! - -The .md files are written in Pandoc flavoured Markdown. The following scripts -form Libreboot's *static site generator* which converts the Markdown files into -HTML, to create the website: +The website and documentation is inside the **www** directory in the +[Git repository](#how-to-download-libreboot-from-the-git-repository), in +Pandoc flavoured Markdown. The website is generated into static HTML via Pandoc +with the following scripts in that directory: - index.sh: generates the news feed (on the News section of the website) - publish.sh: converts an .md file to an .html file - generate.sh: with calls to index.sh and publish.sh, compiles the entire Libreboot website -To view your local version of the website, it is advisable to install an HTTP -server (e.g. nginx, lighttpd) and configure it so that the `www` directory in -your local Git repository is the document root. With this, you can run -`generate.sh` and view your own version of the website locally. This can be -useful for larger changes (including structural) if you're making many large -improvements to the website. However, it is possible to just edit the Markdown -files with a text editor and submit those, or view individual .html files -(generated by publish.sh) in a Web browser (e.g. Firefox). +Use any standard text editor (e.g. Vim, Emacs, Nano, Gedit) to edit the files, +commit the changes and [send patches](#how-to-submit-your-patches). -If you're running a local HTTP server, you can view your local version of the -site by typing `localhost` into your browser's URL bar. - -At present, the site and documentation are optimized for use on the Web (as -HTML, generated by Pandoc), but we would like to possibly support other use -cases, such as PDF documents for printed manuals. +Optionally, you can install a web server (e.g. lighttpd, nginx) locally and +set the document root to the *www* directory in your local Git repository. +With this configuration, you can then generate your local version of the +website and view it by typing `localhost` in your browser's URL bar. General guidelines for submitting patches ----------------------------------------- @@ -64,23 +34,12 @@ General guidelines for submitting patches We require all patches to be submitted under a free license: . -You *must* declare copyright on your work, and declare a free license. Not -declaring copyright, especially if you also don't declare a license, means that -the default restrictive copyright laws apply under the Berne convention. - -If you wish to submit work without copyright, or with permissive terms, then -the *Creative Commons Zero* license is highly recommended. Otherwise, the **GNU -General Public License, version 3 or (at your option) any later version**, is -preferred; we will also accept any other free license. +- GNU General Public License v3 is highly recommended +- For documentation, we require GNU Free Documentation License v1.3 or higher -*We require all documentation and website changes to use the [GNU Free -Documentation License, version 1.3](docs/fdl-1.3.md) or (at your option) any -later version published by the Free Software Foundation; without Invariant -sections, without front cover texts and without back cover texts.* - -Libreboot development is facilitated by *[git](https://git-scm.com/)*, a -*distributed* version control system. You will need to install Git (most -GNU+Linux distributions package it in their repositories). +*Always* declare a license on your work! Not declaring a license means that +the default, restrictive copyright laws apply, which would make your work +non-free. GNU+Linux is generally recommended as the OS of choice, for Libreboot development. @@ -88,27 +47,12 @@ development. General code review guidelines ------------------------------ -Non-core members will push to their own repository, and issue a Pull Request. -Core maintainers of Libreboot can push to the repository, but not to the master -branch; they must push it to a non-master branch, and again issue a Pull -Request. - -An individual or group of people will then review the patch sent by the -contributor. With approval from a core maintainer, or otherwise someone with -merge rights on the repository, the patch will be merged into the official -*master* branch. - -Those with push/merge access on the official Libreboot repository must never -directly push their own patches to the master branch, and they must never -merge their own Pull Request. Regardless of the individual's standing and -frequency of contributions within the project, those who decide whether to -merge a patch will *always* differ from the original contributor. - -These guidelines are *enforced*, to avoid the appearance of a BDFL (Benevolent -Dictator for Life) in the Libreboot project, as one previously existed in the -project. Libreboot is a collectively and democratically governed project. -Maintainers who violate these guidelines may, at the discretion of other -maintainers, have their push/merge rights revoked. +Any member of the public can [submit a patch](#how-to-submit-your-patches). +Members with push access must *never* push directly to the master branch; +issue a Pull Request, and wait for someone else to merge. Never merge your own +work! + +Your patch will be reviewed for quality assurance, and merged if accepted. How to download Libreboot from the Git repository ------------------------------------------------- -- cgit v1.2.3-70-g09d2