Skip to content

Latest commit

 

History

History
205 lines (165 loc) · 7.29 KB

behind-the-curtain.adoc

File metadata and controls

205 lines (165 loc) · 7.29 KB

The Debian Package Management Book — Behind the Curtain of a Free Book

We’ve started a book …​

  • Title: Debian Package Management

  • Authors: Axel Beckert and Frank Hofmann

  • Start: Spring 2013

  • Length: about 500 pages

  • Completely written in readable German

    • Intended audience: advance beginners, professionals

    • An English translation is planned

Contents of the Book

  • describes the package management on dpkg/apt based systems in detail

  • focusses on Debian GNU/Linux, but also fits for derivatives like Ubuntu, LinuxMint, etc.

  • Part 1: Concepts — ideas behind Package Management

  • Part 2: Tools — the programs and their possibilities

  • Part 3: Best Practice — solutions for more complex real-life situations

Status

  • Part 1 and 2: mostly complete

  • Part 3: still things missing

Releases

How we write our book

  • Base:

    • Writing is a creative process and requires a specific mood — it doesn’t work at the touch of a button.

    • Our process is modeled after software development processes

    • Using (free) tools as we need them.

  • Writing at a fixed location: mostly in Zürich and Berlin

    • each author works mostly on his own

    • Exchange via phone, e-mail and video conference

    • occassional explicit meetings about the book (so-called "book sprints")

  • Writing on the road

    • Meeting within the scope of Linux events

    • in the camper van (Axel) and on the train (Frank)

    • also far off locations to find silence, and not to be distracted from the outside world, see http://www.dpmb.org/karte/

Sources of the Book

  • Hosting is done on the platform GitHub

    • without costs for free (freely available) software

    • very popular and known by many developers/readers

    • provides uncomplicated coordination of external contributions

    • provides a simple rendering of AsciiDoc source files

  • Workflow in three steps:

    • clone a local copy of the book repository: git clone git://github.com/dpmb/dpmb.git

    • build the book locally, e.g. with make pdf, make html or dpkg-buildpackage

    • read, comment and improve the source

Versioning

  • Versioning control system (VCS) that we use: Git

    • free, stable and very flexible VCS

    • Combination of central archive, and distributed copies kept on local machines

    • distributed working without permanent need of an internet connection

    • steady synchronising and merging of contents

  • allows …​

    • …​ to temporarily work without internet

    • …​ being able to reconstruct who changed what, and when

    • …​ to revert the changes

Contributing and Feedback

  • With GitHub account: via pull request on GitHub

    1. Click on the top-right fork button on https://github.com/dpmb/dpmb

    2. Make your changes and commit them to your forked GitHub repo:

      • Either clone your own GitHub-Repo locally, make your changes locally, commit them and push them into your forked GitHub repo.

      • Or edit the files of your forked GitHub repo directly in your web browser on the GitHub website.

    3. Open the website of your forked GitHub repo (or reload it) and click on "Pull Request".

  • Without GitHub account: send us your patches by e-mail

    1. Create local copy of our Git repo: git clone git://github.com/dpmb/dpmb.git

    2. Make your changes and commit them locally.

    3. Export patch(es) in files with git format-patch origin/master and send the patches to [email protected].

  • We check the patch or pull request

    • Either we accept the changes or we refuse them

    • If accepted, we "merge" the pull request or apply the patch with git am.

  • Synchronise your local copy (git pull), so that all contributors are in sync.

Software

  • locally

    • Git as revision control system

    • AsciiDoc as platform-independent markup language for the content

      • asciidoc or asciidoctor as primary parser

      • a2x, dblatex and pdflatex for generating the PDF

    • Make for triggering the compilation into the output formats

    • Node.js and Gitbook (installed via npm) for debugging, if the book doesn’t build on Gitbook.

  • on the web

Under Construction

  • Where we’re still working on:

    • Finetuning part 2 — consistent wording, keywords

    • Completion of part 3 — content improvements

    • Work around issues at Gitbook

  • Where we need support for:

    • Best practice part (part 3) — we cannot setup, and verify all scenarios

    • Which problems did you notice with .deb packages, and which tools popped up? How have did you solve the situation?

Alternatives for Publishing we didn’t use

  • Leanpub (primarily e-books, also free book or pay-what-you-want scheme possible)

  • Epubli (Print-on-demand, but also stock printing on behalf and costs of the author; fixed book price in Germany, but also present at epubli.co.uk)

  • Lulu (primarily Print-on-demand)

  • BookBaby (E-books and printed books)

Markdown in comparison to AsciiDoc

  • Simpler, but also less mighty

  • Standard format for books at Leanpub and Gitbook

Variants

Thanks and Contact

Thanks for listening to us. Thanks for reading the book. Thanks for contributing to the book.

Sending Feedback