diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 30 | ||||
| -rw-r--r-- | devel/2_nonpkg.xml | 9 | ||||
| -rw-r--r-- | devel/3_git.xml | 9 | ||||
| -rw-r--r-- | master.xsl | 10 | ||||
| -rw-r--r-- | src/devel/1_preparing.xml (renamed from devel/1_preparing.xml) | 0 | ||||
| -rw-r--r-- | src/devel/2_nonpkg.xml | 31 | ||||
| -rw-r--r-- | src/devel/3_git.xml | 104 | ||||
| -rw-r--r-- | src/devel/4_hello.xml (renamed from devel/4_hello.xml) | 0 | ||||
| -rw-r--r-- | src/devel/5_deepdive.xml (renamed from devel/5_deepdive.xml) | 0 | ||||
| -rw-r--r-- | src/devel/6_security.xml (renamed from devel/6_security.xml) | 0 | ||||
| -rw-r--r-- | src/devel/7_misc.xml (renamed from devel/7_misc.xml) | 0 | ||||
| -rw-r--r-- | src/devel/8_help.xml (renamed from devel/8_help.xml) | 0 | ||||
| -rw-r--r-- | src/devel/develguide.xml (renamed from devel/develguide.xml) | 0 | ||||
| -rw-r--r-- | src/install/1_begin.xml (renamed from install/1_begin.xml) | 0 | ||||
| -rw-r--r-- | src/install/2_req.xml (renamed from install/2_req.xml) | 0 | ||||
| -rw-r--r-- | src/install/installguide.xml (renamed from install/installguide.xml) | 0 | ||||
| -rw-r--r-- | src/pretty.css | 3 |
18 files changed, 179 insertions, 19 deletions
@@ -1,2 +1,2 @@ # Processed source -*.html +out/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..09ff77c --- /dev/null +++ b/Makefile @@ -0,0 +1,30 @@ +.POSIX: + +all: out/html/devel/index.html out/text/develguide.txt \ + out/html/install/index.html out/text/installguide.txt + +out/text/develguide.txt: src/devel/*.xml + @mkdir -p out/text + @printf 'Developer Guide: Generating text...\n' + @xmlto txt -o out/text src/devel/develguide.xml + +out/html/devel/index.html: src/devel/*.xml src/pretty.css + @mkdir -p out/html/devel + @printf 'Developer Guide: Generating HTML...\n' + @xmlto html -m master.xsl -o out/html/devel src/devel/develguide.xml + @cp src/pretty.css out/html/devel/ + +out/text/installguide.txt: src/install/*.xml + @mkdir -p out/text + @printf 'Install Guide: Generating text...\n' + @xmlto txt -o out/text src/install/installguide.xml + +out/html/install/index.html: src/install/*.xml src/pretty.css + @mkdir -p out/html/install + @printf 'Install Guide: Generating HTML...\n' + @xmlto html -m master.xsl -o out/html/install src/install/installguide.xml + @cp src/pretty.css out/html/install/ + +install: + @mkdir -p "${DESTDIR}"/usr/share/doc/adelie-handbook/ + @cp -r out/* "${DESTDIR}"/usr/share/doc/adelie-handbook/ diff --git a/devel/2_nonpkg.xml b/devel/2_nonpkg.xml deleted file mode 100644 index f43a927..0000000 --- a/devel/2_nonpkg.xml +++ /dev/null @@ -1,9 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<chapter label="2" id="nonpkg"> - <title>Non-Package Development</title> - <para></para> - <section> - <title></title> - <para></para> - </section> -</chapter> diff --git a/devel/3_git.xml b/devel/3_git.xml deleted file mode 100644 index 8eeb5fb..0000000 --- a/devel/3_git.xml +++ /dev/null @@ -1,9 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<chapter label="3" id="git"> - <title>Git Basics</title> - <para></para> - <section> - <title></title> - <para></para> - </section> -</chapter> diff --git a/master.xsl b/master.xsl new file mode 100644 index 0000000..6c2297c --- /dev/null +++ b/master.xsl @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="utf-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + <xsl:param name="use.id.as.filename" select="'1'"/> + <xsl:param name="admon.graphics" select="'1'"/> + <xsl:param name="admon.graphics.path"></xsl:param> + <xsl:param name="chunk.section.depth" select="0"></xsl:param> + <xsl:param name="html.stylesheet" select="'pretty.css'"/> +</xsl:stylesheet> diff --git a/devel/1_preparing.xml b/src/devel/1_preparing.xml index 0966a44..0966a44 100644 --- a/devel/1_preparing.xml +++ b/src/devel/1_preparing.xml diff --git a/src/devel/2_nonpkg.xml b/src/devel/2_nonpkg.xml new file mode 100644 index 0000000..c844be9 --- /dev/null +++ b/src/devel/2_nonpkg.xml @@ -0,0 +1,31 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter label="2" id="nonpkg"> + <title>Non-Package Development</title> + <para>There are a number of ways to contribute to the development of Adélie Linux that do not involve packaging. This chapter will introduce you to other Adélie Linux projects and how to set up a development environment for each one.</para> + <section> + <title>Developing Adélie Documentation</title> + <para>In this section, you will learn:</para> + <itemizedlist> + <listitem><para>How documentation and guides like this one are authored; and</para></listitem> + <listitem><para>How you can configure your environment to edit and author documentation for Adélie Linux.</para></listitem> + </itemizedlist> + <section> + <title>Authorship of Documentation</title> + <para>The Adélie Linux Documentation Set, including the guide that you are reading, is written in a format called DocBook. DocBook is somewhat similar to HTML in that it uses <firstterm>tags</firstterm> to define the semantics of the document, but the tags DocBook uses are different from HTML's and focus on creation of books and manuals.</para> + <para>The main Documentation Set is written in English, but we are happy to accept translations of our documentation into other languages.</para> + <para>You can contribute corrections, additions, or translations of any portion of our documentation by emailing the adelie-docs mailing list with your patch, or by creating a merge request on the Documentation GitLab page. For more information about using Git to create patches and merge requests, see chapter 3.</para> + </section> + <section> + <title>Configuring Your Environment</title> + <para>You will need to install the <package>xmlto</package> package to ensure your changes leave the documentation syntatically valid. After making your changes, run the <command>xmlto</command> command on the primary file (for this guide, <filename>develguide.xml</filename>) and ensure there are no errors.</para> + </section> + </section> + <section> + <title>Spread the Word</title> + <para>There are many ways to spread the word about Adélie Linux. + Talk to your friends about Adélie Linux and the benefits of libre software, including security, speed, and less need to purchase new computers every year. + Have civil discussions on forums, newsgroups, and social media. + If you're a student, talk to your school's Computer Science department and see if they are interested in a lab with Adélie Linux. + By spreading the word, you're helping more people learn and spreading our ideas and goals worldwide. Thank you!</para> + </section> +</chapter> diff --git a/src/devel/3_git.xml b/src/devel/3_git.xml new file mode 100644 index 0000000..ed97eca --- /dev/null +++ b/src/devel/3_git.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter label="3" id="git"> + <title>Git Basics</title> + <para>The majority of Adélie Linux projects are stored in a distributed version control system called Git. + In this chapter, we will see an overview of how Git works, find out where its documentation lives, and learn about Adélie-specific workflows in Git.</para> + <section> + <title>Getting Started with Git</title> + <para>In this section, you will learn:</para> + <itemizedlist> + <listitem><para>What Git and distributed version control systems provide;</para></listitem> + <listitem><para>How to configure Git for work on Adélie Linux projects; and</para></listitem> + <listitem><para>Where to find documentation about Git.</para></listitem> + </itemizedlist> + <section> + <title>What is Git?</title> + <para>A <firstterm>version control system</firstterm> is a system that keeps track of a collection of related files, called a <firstterm>repository</firstterm>, and how they change over time. + If you are familiar with <productname>Mac OS X</productname>'s Time Machine functionality, a version control system is similar to this; it keeps a record of each file, when it was changed, and who changed it. + The primary difference is that a version control system only saves records of files when you explicitly tell it to do so. This saving of a record is called a <firstterm>commit</firstterm>, and the list of all commits is called a <firstterm>commit log</firstterm>.</para> + <para>A <firstterm>distributed version control system</firstterm> allows many people to have their own copies of the repository containing the full commit log. When a person wants to provide their commits to others, they <firstterm>push</firstterm> their commits to a central server. + Typically, people work on their own <firstterm>branch</firstterm>, or private tree of files. When a person pushes their changed branch to the central server, it allows them to <firstterm>merge</firstterm> other branches.</para> + <para><firstterm>Git</firstterm> is a distributed version control system that runs on many different kinds of computers, and is very popular in open source development. The Adélie Linux distribution uses Git to track everything from the package repositories, to the documentation set, to libraries and other software written for Adélie Linux.</para> + <para>Git allows us to maintain a record of who has contributed to the project, the date they contributed, and what changes they contributed. It is therefore very important that you configure Git on your system to have your name and email address, so that the commit log attributes you correctly.</para> + </section> + <section> + <title>Configuring Git</title> + <para>If you have not already done so, you must first provide your name and email address to Git. You may do this by running the following two commands:</para> + <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.name</parameter> <userinput>"Your Name"</userinput></command></para> + <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.email</parameter> <userinput>"email@address.tld"</userinput></command></para> + <para>If you have a PGP key (used for signing electronic messages), and it is publicly known and cross-signed, you should additionally provide this to Git. This will allow more provability that you are the one who created a commit. You may do this by running the following two commands:</para> + <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>user.signingkey</parameter> <userinput>YourPublicKeyFingerprint</userinput></command></para> + <para><prompt>$</prompt> <command>git <parameter>config</parameter> <parameter>--global</parameter> <parameter>commit.gpgsign</parameter> <parameter>true</parameter></command></para> + </section> + <section> + <title>Learning More about Git</title> + <para>There are many helpful resources available for you to learn more about Git. + You may install the <package>git-doc</package> package on your Adélie computer for easy access to the built-in manuals. + Additionally, if you have access to the World Wide Web, you may read the freely-licensed Pro Git book at https://git-scm.com/book/en/v2. + There are also a number of mailing lists for starting out and working with Git.</para> + </section> + </section> + <section> + <title>Using Git with Adélie</title> + <para>In this section, you will learn:</para> + <itemizedlist> + <listitem><para>How the Adélie Linux distribution uses Git branches and commits;</para></listitem> + <listitem><para>How to write a good, informative commit message; and</para></listitem> + <listitem><para>A guideline on how frequently to make commits and merge requests.</para></listitem> + </itemizedlist> + <section> + <title>Using Branches</title> + <para>A <firstterm>branch</firstterm> is a self-contained copy of a project's files. Using branches allow your changes to be reviewed quickly and, if approved, merged in to the Adélie Linux source quickly. + A branch should be a single "unit of work". That is, a branch should have a single goal in mind. Sometimes a branch can contain many commits; for instance, your goal may be "update the Gnome Office packages". In that case, you would have at least one commit for each Gnome Office package. + However, sometimes a branch only needs one commit. This can be useful for simple bug fixes, or bumping a single package's version.</para> + <para>Branches should have a name that reflects their goal. A branch name such as <literal>bugfix</literal> or <literal>version</literal> is unclear and doesn't communicate the goal of the branch. A branch name such as <literal>gnumeric-1.12.35-update</literal> or <literal>fix-boot-on-g3</literal> is clear and concisely states the branch goal.</para> + <para>If you are not currently an Adélie Linux developer, you will create the branches in your <firstterm>fork</firstterm>, which is a private copy of the repository that is owned by you. If you are an Adélie Linux developer, you can create the branch in your own private fork or the main repository. For more information about creating forks, see the GitLab documentation.</para> + </section> + <section> + <title>Commits</title> + <para>A commit message should have the following structure:</para> + <screenco> + <areaspec> + <area id="commit_area" coords="1 1"/> + <area id="commit_summary" coords="1 7"/> + <area id="commit_detail" coords="3"/> + <area id="commit_signedoff" coords="5"/> + <area id="commit_acked" coords="6"/> + </areaspec> + <screen>area: summary of change + +Multi-line details of change, if necessary. + +Signed-off-by: Your Name <email@address.tld> +Acked-by: Developer Name <email@adelielinux.org> + </screen> + <calloutlist> + <callout arearefs="commit_area"> + <para>The area changed by the commit. For source code, this is typically the module name (such as <filename>string</filename> or <filename>gnulib</filename>). For packages, this is the full name of the package, such as <filename>user/dejagnu</filename>.</para> + </callout> + <callout arearefs="commit_summary"> + <para>A brief summary of the commit. The summary line should be less than 60 characters, and be a concise summary of the change made.</para> + </callout> + <callout arearefs="commit_detail"> + <para>A detailed summary of the commit. You may expand on the rationale for the commit, or provide more information than you could in the summary line.</para> + </callout> + <callout arearefs="commit_signedoff"> + <para>If you are not yet an Adélie Linux developer, use the <parameter>--signoff</parameter> parameter to <command>git</command> to reflect that you agree to the contribution guidelines of the repository.</para> + </callout> + <callout arearefs="commit_acked"> + <para>If you communicated with an Adélie Linux developer about this change before sending the commit, add the <literal>Acked-by</literal> line to reflect such. This will make it easier for further review to continue.</para> + </callout> + </calloutlist> + </screenco> + <para>There are a few different standards for how often you should commit your work, depending on the repository to which you are contributing. + Some repositories contain guidelines in their Contribution Guide, found in the <filename>CONTRIBUTING.rst</filename> file in the root of the repository. + As a general guideline, when you are working on a source code repository, each commit should be one "logical change". + This could be adding a new function to an API, or changing an algorithm and ensuring all other files have the updated algorithm.</para> + <para>Similarly, when you are working on a package repository, you should use one commit per package that you change. + For instance, if you "bump" or update the version of three packages, you would use one commit for each of the three packages, for a total of three commits. + This allows an Adélie Linux developer to review each package's change separately. + There are some reasons you may want a single commit to hold changes to multiple packages. + For example, if you are updating the license fields of many packages, you may want a single commit with a message similar to <literal>main/libx*: update licenses on X11 libraries</literal>.</para> + </section> + </section> +</chapter> diff --git a/devel/4_hello.xml b/src/devel/4_hello.xml index cc45af6..cc45af6 100644 --- a/devel/4_hello.xml +++ b/src/devel/4_hello.xml diff --git a/devel/5_deepdive.xml b/src/devel/5_deepdive.xml index a0eac6b..a0eac6b 100644 --- a/devel/5_deepdive.xml +++ b/src/devel/5_deepdive.xml diff --git a/devel/6_security.xml b/src/devel/6_security.xml index 95008c0..95008c0 100644 --- a/devel/6_security.xml +++ b/src/devel/6_security.xml diff --git a/devel/7_misc.xml b/src/devel/7_misc.xml index f806ab7..f806ab7 100644 --- a/devel/7_misc.xml +++ b/src/devel/7_misc.xml diff --git a/devel/8_help.xml b/src/devel/8_help.xml index 4f43069..4f43069 100644 --- a/devel/8_help.xml +++ b/src/devel/8_help.xml diff --git a/devel/develguide.xml b/src/devel/develguide.xml index 8447c80..8447c80 100644 --- a/devel/develguide.xml +++ b/src/devel/develguide.xml diff --git a/install/1_begin.xml b/src/install/1_begin.xml index bbd4951..bbd4951 100644 --- a/install/1_begin.xml +++ b/src/install/1_begin.xml diff --git a/install/2_req.xml b/src/install/2_req.xml index f9a1b0f..f9a1b0f 100644 --- a/install/2_req.xml +++ b/src/install/2_req.xml diff --git a/install/installguide.xml b/src/install/installguide.xml index 4aad4f5..4aad4f5 100644 --- a/install/installguide.xml +++ b/src/install/installguide.xml diff --git a/src/pretty.css b/src/pretty.css new file mode 100644 index 0000000..95b4cd9 --- /dev/null +++ b/src/pretty.css @@ -0,0 +1,3 @@ +body { + font-family: 'Liberation Sans',sans-serif; +} |