Merge branch 'pks/docs-improvements'

README.md

@@ -27,6 +27,27 @@ with any kind of software without having to release its source code.
 Additionally, the example code has been released to the public domain (see the
 [separate license](examples/COPYING) for more information).
 
+Table of Contents
+=================
+
+* [Quick Start](#quick-start)
+* [Getting Help](#getting-help)
+* [What It Can Do](#what-it-can-do)
+* [Optional dependencies](#optional-dependencies)
+* [Initialization](#initialization)
+* [Threading](#threading)
+* [Conventions](#conventions)
+* [Building libgit2 - Using CMake](#building-libgit2---using-cmake)
+    * [Building](#building)
+    * [Installation](#installation)
+    * [Advanced Usage](#advanced-usage)
+    * [Compiler and linker options](#compiler-and-linker-options)
+    * [MacOS X](#macos-x)
+    * [Android](#android)
+* [Language Bindings](#language-bindings)
+* [How Can I Contribute?](#how-can-i-contribute)
+* [License](#license)
+
 Quick Start
 ===========
 
@@ -48,8 +69,8 @@ Quick Start
 2. Create the cmake build environment: `cmake ..`
 3. Build libgit2: `cmake --build .`
 
-Trouble with these steps?  Read `TROUBLESHOOTING.md`.  More detailed build
-guidance is available below.
+Trouble with these steps?  Read our (troubleshooting guide)[docs/troubleshooting.md].
+More detailed build guidance is available below.
 
 Getting Help
 ============
@@ -149,12 +170,12 @@ require assistance coordinating this, simply have the worker threads call
 Threading
 =========
 
-See [THREADING](THREADING.md) for information
+See [threading](docs/threading.md) for information
 
 Conventions
 ===========
 
-See [CONVENTIONS](CONVENTIONS.md) for an overview of the external
+See [conventions](docs/conventions.md) for an overview of the external
 and internal API/coding conventions we use.
 
 Building libgit2 - Using CMake
@@ -196,7 +217,7 @@ run the index tests:
     $ ./libgit2_clar -sindex
 
 To run a single test named `index::racy::diff`, which corresponds to the test
-function (`test_index_racy__diff`)[https://github.com/libgit2/libgit2/blob/master/tests/index/racy.c#L23]:
+function [`test_index_racy__diff`](https://github.com/libgit2/libgit2/blob/master/tests/index/racy.c#L23):
 
     $ ./libgit2_clar -sindex::racy::diff
 
@@ -233,6 +254,15 @@ The following CMake variables are declared:
 - `THREADSAFE`: Build libgit2 with threading support (defaults to ON)
 - `STDCALL`: Build libgit2 as `stdcall`. Turn off for `cdecl` (Windows; defaults to ON)
 
+To list all build options and their current value, you can do the
+following:
+
+	# Create and set up a build directory
+	$ mkdir build
+	$ cmake ..
+	# List all build options and their values
+	$ cmake -L
+
 Compiler and linker options
 ---------------------------
 
@@ -343,10 +373,10 @@ We welcome new contributors!  We have a number of issues marked as
 and
 ["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22)
 that are good places to jump in and get started.  There's much more detailed
-information in our list of [outstanding projects](PROJECTS.md).
+information in our list of [outstanding projects](docs/projects.md).
 
-Please be sure to check the [contribution guidelines](CONTRIBUTING.md) to
-understand our workflow, and the libgit2 [coding conventions](CONVENTIONS.md).
+Please be sure to check the [contribution guidelines](docs/contributing.md) to
+understand our workflow, and the libgit2 [coding conventions](docs/conventions.md).
 
 License
 ==================================

CONTRIBUTING.md → docs/contributing.md

@@ -97,7 +97,7 @@ Before wrapping up a PR, you should be sure to:
 
 * Write tests to cover any functional changes
 * Update documentation for any changed public APIs
-* Add to the [`CHANGELOG.md`](CHANGELOG.md) file describing any major changes
+* Add to the [`changelog.md`](changelog.md) file describing any major changes
 
 ## Unit Tests
 
@@ -168,10 +168,8 @@ function and type naming, code formatting, and testing.
 
 We like to keep the source code consistent and easy to read.  Maintaining
 this takes some discipline, but it's been more than worth it.  Take a look
-at the [conventions
-file](https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md).
+at the [conventions file](conventions.md).
 
 ## Starter Projects
 
-See our [projects
-list](https://github.com/libgit2/libgit2/blob/development/PROJECTS.md).
+See our [projects list](projects.md).

PROJECTS.md → docs/projects.md

@@ -10,8 +10,8 @@ ideas that no one is actively working on.
 
 ## Before You Start
 
-Please start by reading the [README.md](README.md),
-[CONTRIBUTING.md](CONTRIBUTING.md), and [CONVENTIONS.md](CONVENTIONS.md)
+Please start by reading the [README.md](../README.md),
+[contributing.md](contributing.md), and [conventions.md](conventions.md)
 files before diving into one of these projects.  Those explain our work
 flow and coding conventions to help ensure that your work will be easily
 integrated into libgit2.

docs/release.md

@@ -15,8 +15,8 @@ We aim to release once every six months. We start the process by opening an issu
     - [ ] Make a release candidate
     - [ ] Plug any final leaks
     - [ ] Fix any last-minute issues
-    - [ ] Make sure CHANGELOG reflects everything worth discussing
-    - [ ] Update the version in CHANGELOG and the header
+    - [ ] Make sure changelog.md reflects everything worth discussing
+    - [ ] Update the version in changelog.md and the header
     - [ ] Produce a release candidate
     - [ ] Tag
     - [ ] Create maint/v0.X
@@ -26,13 +26,13 @@ We tag at least one release candidate. This RC must carry the new version in the
 
 Preparing the first release candidate includes updating the version number of libgit2 to the new version number. To do so, a pull request shall be submitted that adjusts the version number in the following places:
 
-- CHANGELOG.md
+- docs/changelog.md
 - include/git2/version.h
 - package.json
 
 As soon as the pull request is merged, the merge commit shall be tagged with a lightweight tag.
 
-The tagging happens via GitHub's "releases" tab which lets us attach release notes to a particular tag. In the description we include the changes in `CHANGELOG.md` between the last full release. Use the following as a base for the release notes
+The tagging happens via GitHub's "releases" tab which lets us attach release notes to a particular tag. In the description we include the changes in `docs/changelog.md` between the last full release. Use the following as a base for the release notes
 
     This is the first release of the v0.X series, <codename>. The changelog follows.