typos

[lbwsite.git] / CONTRIBUTING.md

Working With the LBW Web Site\r
=============================\r
\r
\r
Requirements\r
------------\r
\r
You need a POSIX environment, i.e. some variety of Linux/Unix, OS X or Cygwin\r
with a Bash-like shell.\r
\r
1. Install [Git] [1] via your distribution's package manager.\r
\r
2. Install Perl and the Perl [Template Toolkit] [2] library via your package\r
   manager or CPAN.\r
\r
\r
Initial Repository Setup\r
------------------------\r
\r
You need to do these steps once before making any changes to the site.\r
\r
1. Clone the Git repository:\r
\r
        git clone https://linuxbierwanderung.com/lbwsite.git\r
\r
   This will create a directory 'lbwsite' in the current directory. This is\r
   is your working copy of the repository. Note that this not only contains\r
   the latest version of the repo but is a separate repository in its own right\r
   with the whole change history and all branches (see below) existing at the\r
   time of the checkout.\r
\r
   The repository you created the clone from is a so-called "remote" and named\r
   "origin" by convention. It is the default target when you upload your\r
   changes with `git push` and when you retrieve changes by others with `git\r
   pull` (or `fetch`). You can list the defined remote repositories with:\r
\r
        git remote -v\r
\r
2. Change into the `lbwsite` directory.\r
\r
3. Create a new branch for your changes::\r
\r
        git checkout -b <new-branch-name>\r
\r
  Use something like "feature/newdesign" or "bugfix/headerlayout" as the branch\r
  name. This step is optional but highly recommended, since it makes it much\r
  easier to submit or create a patch of your changes later and to synchronize\r
  to the master repository while keeping your changes separate while working on\r
  them. Creating a branch also automatically "activates" it, so when you commit\r
  any changes, they are commited to this branch.\r
\r
  You can list the existing branches with::\r
\r
        git branch -v\r
\r
  The default branch which should exist in every (new) repository is called\r
  "master".\r
\r
  You can change between branches with:\r
\r
        git checkout <branch-name>\r
\r
  Yes, I know, it's silly that the command is also called checkout. That's Git\r
  for you.\r
\r
\r
Building the Site\r
-----------------\r
\r
Open a shell, change into the `lbwsite` directory and run:\r
\r
    ./build.sh\r
\r
This does a few things:\r
\r
1. It creates the output directory `out` beneath the current directory (and\r
   deletes) an existing one.\r
2. Copies the background images to it.\r
3. Builds the site from the template files in `src` via the `ttree` command,\r
   using the file `ttreerc` as the configuration.\r
4. Creates a new empty git repository in `out/lbwsite.git`.\r
5. Mirrors your repository in `lbwsite` into `out/lbwsite.git`.\r
6. Does some Git repository adminstrative stuff.\r
\r
You can view the generated site by opening `out/index.html` in your browser.\r
\r
\r
Making Changes\r
--------------\r
\r
Open a shell, change into the `lbwsite` directory and make sure your repository\r
has the latest changes from the "origin" remote repository:\r
\r
    git pull\r
\r
This will fetch changes from the "origin" and update your working copy with\r
them (i.e. merge them with your changes). `git pull` is shorthand for `git\r
fetch` followed by `git merge FETCH_HEAD`.\r
\r
Then make your changes to the source files under the `src` directory.\r
\r
### Updating Your Branch\r
\r
(Ignore this section if you do not use your own branch.)\r
\r
Note that `git pull` only works on the currently active branch. If you have\r
created and activated a new branch to work on your changes, you need to change\r
to (activate) the "master" branch to merge the remote changes into your local\r
"master" branch:\r
\r
    git checkout master\r
    git pull\r
\r
If this pulls any changes and you want to include them into your branch,\r
activate your branch and merge the new changes from the "master" branch into\r
it:\r
\r
    git checkout <my-branch>\r
    git merge master\r
\r
\r
### Commiting Changes\r
\r
You can check which files have changed or which are new with:\r
\r
    git status\r
\r
Note that the file `.gitignore` defines patterns for files and directories\r
whose changes are ignored. The output directory `out` is listed in there, so\r
the generated site files to not show up with `git status`.\r
\r
To see *what* has changed:\r
\r
    git diff\r
\r
This will give you a unified diff of changes that have not been *added* (see\r
below) yet.\r
\r
If you are happy with a change, you need to *commit* it. This registers a\r
*changeset* in *your local* repository. To distribute the change to others,\r
you'll either need to *push* these changes to another (remote) repository (if\r
you're allowed to) or prepare a patch and send to someone, e.g. via email.\r
\r
Before you can commit changes to a file (or several) you need to *add* the\r
file(s) to the *staging area*, i.e. the collection of changes which will be\r
commited with the next `commit` command. You can either specify the file(s) to\r
add, e.g.:\r
\r
    git add README.md\r
\r
or add all changed files, even newly created ones, which hadn't been under\r
version control yet, with:\r
\r
    git add -A\r
\r
You have to repeat the `add` command after each new change, which you want to\r
go into the next commit. Check with `git status` regularly for any un-added\r
changes, esp. before issuing the `commit` command. To see a diff of the changes\r
that go into the next commit:\r
\r
    git diff --cached\r
\r
Before you commit, rebuild the site and check that everything works as\r
intended.\r
\r
Finally, commit your changes, giving a meaningful (!) log message:\r
\r
    git commit -m "Fixed URL in README file"\r
\r
This will commit all added changes.\r
\r
Repeat the edit, `git add`, `git commit` cycle for each change that constitutes\r
a defined, separate change (how much goes into each commit is a philosophical\r
discussion not touched here).\r
\r
\r
Distributing Your Changes\r
-------------------------\r
\r
How this is done depends on whether you have write access to the "origin" (see\r
above) remote repository or not.\r
\r
If you don't, you can pack up a series of commits into a bundle, suited for\r
sending via email with:\r
\r
    git bundle create my-branch.bundle master..<my-branch>\r
\r
This will make a bundle with all changes/commits that separate your branch from\r
the "master" branch. Send the `my-branch.bundle` file to the owner of the\r
"origin" repository and (s)he'll hopyfully know what to do with it and merge\r
your changes. ;)\r
\r
*This section to be continued...*\r
\r
\r
[1]: https://git-scm.com/\r
[2]: http://www.template-toolkit.org/\r