We are actively looking for volunteers to proofread documentation. If you come across an error, simply send an email to "corrections AT qos dot ch" with a copy of the erroneous paragraph and your corrections. Contributing to open source can be as easy as that. Once we have your corrections, we'll make the necessary changes. If you would like to make extensive corrections, then please read on.
For starters, the documentation source for each project is located under the site/ folder of the project source code. For example, logback-site/ for logback and slf4j-site/ for SLF4J. More importantly, the HTML pages located on each project's web-site, i.e. the documentation, can be found as-is under the *-site/ folder. It's all there in plain HTML.
QOS.ch projects use git as their version control system. If you wish to contribute to one of the projects hosted at QOS.ch, then you should be at least a little familiar with git. If you are not, there are plenty of books available on the subject. We recommend pro-git as a good introduction.
Let mistletoe be the project you wish to contribute to. You should begin by forking mistletoe's official repository at http://github.com/ceki/mistletoe. The documentation for the mistletoe project will be located under the mistletoe-site/ folder. For a different project, the url would be modified accordingly. For example, for the logback project, the repository is http://github.com/qos-ch/logback and the documentation is located under the logback-site folder. Note that you first need to register with github before being allowed to fork.
You would then work on a clone of your repository, the so called fork, and on occasion push the results to your repository on github.
Let $LOGBACK_HOME denote the folder where your clone of logback resides on your local hard drive. As mentioned above, source for the documentation for the logback project is formatted in plain HTML. These documentation source is located under the $LOGBACK_HOME/logback-site/src/site/pages/ folder. You can view the documentation in your browser as any other HTML file located on your hard drive. Compared to the documentation on the logback web-site, loading the HTML from the source files will lack images but otherwise should be close to the end-result.
To merge the images issue the "mvn compile site" command from the $LOGBACK_HOME/logback-site/ folder. The final result will be placed under the $LOGBACK_HOME/logback-site/ folder. The contents of this folder are in principle identical to the contents shown on the logback web-site. The same approach is used for managing documentation for all QOS.ch projects, including SLF4J, mistletoe, cal10n, etc.
Having your contribution merged into the official repository implies that the project maintainer is able to read and understand its contents. As obvious as this requirement is, it is easily forgotten.
Do not change the format or indentation of source files. Doing so is the worst mistake you can make while working on a contribution.
Since your contribution will be eventually applied in the form of a patch, you should make sure that your intended changes can be easily read as a patch. The "git diff" command is your friend in this regard. Changing the formatting or indentation of source files will invariably render your contributions unusable. Do not change the format or indentation of source files. Doing so is the worst mistake you can make while working on a contribution.
By convention, on Windows machines we enable git's autocrlf feature in .gitconfig file. Here is the relevant configuration snippet to add to .gitconfig:
[core]
autocrlf = true
By enabling autocrlf feature on Windows, git will convert CRLF at the end of lines in text files to LF when reading from the filesystem, and convert in reverse when writing to the filesystem. This ensures that text files can be exchanged seamlessly across Windows and Linux machines.
As a general rule, as long as the patches corresponding to your commits can be studied by a human reader, i.e. the project maintainers, your contributions have a much higher chance of being integrated. Just don't mess with the indentation and keep your commits focused.
In order to merge your contributions into the official repository, the maintainer has to either manually apply your changes by hand by studying the given individual commit.
Assuming the maintainer has already verified the commit, the process of applying the commit can be semi-automated as follows. Assume that the first 6 characters of SHA1 of the commit to merge is "4589AB". Let /mistletoe be the folder where the official repository is located on the maintainer's computer. Let /mistletoe.alice be the folder where the maintainer cloned Alice's repository, where Alice is a contributor.
mkdir /patches cd /mistletoe.alice # create patches for commit 4589AB in the /patches directory git format-patch --ignore-space-at-eol -b -w -o ~/patches/ ^4589AB^1 4589AB # now apply the patches just created cd /mistletoe git apply --whitespace fix /patches/0001-some-description.patch git apply --whitespace fix /patches/0002-some-description.patch ... git apply --whitespace fix /patches/000N-some-description.patch
Note that even in this semi-automated procedure, the maintainer will verify the commit. If the commit is unreadable because of indentation changes, the contribution is likely to be lost. Caveat emptor.