CONTRIBUTING.md

   1 Working With the LBW Web Site
   2 =============================
   3
   4
   5 Requirements
   6 ------------
   7
   8 You need a POSIX environment, i.e. some variety of Linux/Unix, OS X or Cygwin
   9 with a Bash-like shell.
  10
  11 1. Install [Git] [1] via your distribution's package manager.
  12
  13 2. Install Perl and the Perl [Template Toolkit] [2] library via your package
  14    manager or CPAN.
  15
  16
  17 Initial Repository Setup
  18 ------------------------
  19
  20 You need to do these steps once before making any changes to the site.
  21
  22 1. Clone the Git repository:
  23
  24         git clone https://linuxbierwanderung.com/lbwsite.git
  25
  26    This will create a directory 'lbwsite' in the current directory. This is
  27    is your working copy of the repository. Note that this not only contains
  28    the latest version of the repo but is a separate repository in its own right
  29    with the whole change history and all branches (see below) existing at the
  30    time of the checkout.
  31
  32    The repository you created the clone from is a so-called "remote" and named
  33    "origin" by convention. It is the default target when you upload your
  34    changes with `git push` and when you retrieve changes by others with `git
  35    pull` (or `fetch`). You can list the defined remote repositories with:
  36
  37         git remote -v
  38
  39 2. Change into the `lbwsite` directory.
  40
  41 3. Create a new branch for your changes::
  42
  43         git checkout -b <new-branch-name>
  44
  45   Use something like "feature/newdesign" or "bugfix/headerlayout" as the branch
  46   name. This step is optional but highly recommended, since it makes it much
  47   easier to submit or create a patch of your changes later and to synchronize
  48   to the master repository while keeping your changes separate while working on
  49   them. Creating a branch also automatically "activates" it, so when you commit
  50   any changes, they are commited to this branch.
  51
  52   You can list the existing branches with::
  53
  54         git branch -v
  55
  56   The default branch which should exist in every (new) repository is called
  57   "master".
  58
  59   You can change between branches with:
  60
  61         git checkout <branch-name>
  62
  63   Yes, I know, it's silly that the command is also called checkout. That's Git
  64   for you.
  65
  66
  67 Building the Site
  68 -----------------
  69
  70 Open a shell, change into the `lbwsite` directory and run:
  71
  72     ./build.sh
  73
  74 This does a few things:
  75
  76 1. It creates the output directory `out` beneath the current directory (and
  77    deletes) an existing one.
  78 2. Copies the background images to it.
  79 3. Builds the site from the template files in `src` via the `ttree` command,
  80    using the file `ttreerc` as the configuration.
  81 4. Creates a new empty git repository in `out/lbwsite.git`.
  82 5. Mirrors your repository in `lbwsite` into `out/lbwsite.git`.
  83 6. Does some Git repository adminstrative stuff.
  84
  85 You can view the generated site by opening `out/index.html` in your browser.
  86
  87
  88 Making Changes
  89 --------------
  90
  91 Open a shell, change into the `lbwsite` directory and make sure your repository
  92 has the latest changes from the "origin" remote repository:
  93
  94     git pull
  95
  96 This will fetch changes from the "origin" and update your working copy with
  97 them (i.e. merge them with your changes). `git pull` is shorthand for `git
  98 fetch` followed by `git merge FETCH_HEAD`.
  99
 100 Then make your changes to the source files under the `src` directory.
 101
 102 ### Updating Your Branch
 103
 104 (Ignore this section if you do not use your own branch.)
 105
 106 Note that `git pull` only works on the currently active branch. If you have
 107 created and activated a new branch to work on your changes, you need to change
 108 to (activate) the "master" branch to merge the remote changes into your local
 109 "master" branch:
 110
 111     git checkout master
 112     git pull
 113
 114 If this pulls any changes and you want to include them into your branch,
 115 activate your branch and merge the new changes from the "master" branch into
 116 it:
 117
 118     git checkout <my-branch>
 119     git merge master
 120
 121
 122 ### Commiting Changes
 123
 124 You can check which files have changed or which are new with:
 125
 126     git status
 127
 128 Note that the file `.gitignore` defines patterns for files and directories
 129 whose changes are ignored. The output directory `out` is listed in there, so
 130 the generated site files to not show up with `git status`.
 131
 132 To see *what* has changed:
 133
 134     git diff
 135
 136 This will give you a unified diff of changes that have not been *added* (see
 137 below) yet.
 138
 139 If you are happy with a change, you need to *commit* it. This registers a
 140 *changeset* in *your local* repository. To distribute the change to others,
 141 you'll either need to *push* these changes to another (remote) repository (if
 142 you're allowed to) or prepare a patch and send to someone, e.g. via email.
 143
 144 Before you can commit changes to a file (or several) you need to *add* the
 145 file(s) to the *staging area*, i.e. the collection of changes which will be
 146 commited with the next `commit` command. You can either specify the file(s) to
 147 add, e.g.:
 148
 149     git add README.md
 150
 151 or add all changed files, even newly created ones, which hadn't been under
 152 version control yet, with:
 153
 154     git add -A
 155
 156 You have to repeat the `add` command after each new change, which you want to
 157 go into the next commit. Check with `git status` regularly for any un-added
 158 changes, esp. before issuing the `commit` command. To see a diff of the changes
 159 that go into the next commit:
 160
 161     git diff --cached
 162
 163 Before you commit, rebuild the site and check that everything works as
 164 intended.
 165
 166 Finally, commit your changes, giving a meaningful (!) log message:
 167
 168     git commit -m "Fixed URL in README file"
 169
 170 This will commit all added changes.
 171
 172 Repeat the edit, `git add`, `git commit` cycle for each change that constitutes
 173 a defined, separate change (how much goes into each commit is a philosophical
 174 discussion not touched here).
 175
 176
 177 Distributing Your Changes
 178 -------------------------
 179
 180 You can pack up a series of commits into a bundle, suited for sending via email
 181 with:
 182
 183     git bundle create my-branch.bundle origin/master..<my-branch>
 184
 185 This will make a bundle with all changes/commits that separate your branch from
 186 the "master" branch. Send the `my-branch.bundle` file to the owner of the
 187 "origin" repository, perhaps via the mailing list, and (s)he'll hopefully know
 188 what to do with it and merge your changes. 😀
 189
 190 *This section to be continued...*
 191
 192
 193 [1]: https://git-scm.com/
 194 [2]: http://www.template-toolkit.org/