expand on documentation

CONTRIBUTING.md

@@ -1,56 +1,32 @@
 # Contributing to `dugite-native`
 
-As these scripts are dependent on the OS you have setup, I've not spent much
-time testing things out about the local development experience.
+[fork]: https://github.com/desktop/dugite-native/fork
+[pr]: https://github.com/desktop/dugite-native/compare
+[code-of-conduct]: CODE_OF_CONDUCT.md
+[documentation]: docs/making-changes.md
 
-## Setup
+Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
 
-You'll need a bash environment to run these scripts, and you should be able
-to emulate the behaviour of Travis by setting environment variables
+Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.
 
-```
-GIT_LFS_URL=https://github.com/git-lfs/git-lfs/releases/download/v1.5.5/git-lfs-darwin-amd64-1.5.5.tar.gz \
-GIT_LFS_CHECKSUM=2227668c76a07931dd387602f67c99d5d42f0a99c73b76f8949bbfe3a4cc49c7 \
-script/build-macos.sh ./git /tmp/build/git/
-```
+## Submitting a pull request
 
-Please :thumbsup: this issue https://github.com/desktop/dugite-native/issues/26
-if you encounter friction with running things locally and would like it to be
-easier.
+0. [Fork][fork] and clone the repository
+0. Look over the [documentation][documentation] on how and where to make changes
+0. Create a new branch: `git checkout -b my-branch-name`
+0. Make your change
+0. Push to your fork and [submit a pull request][pr]
+0. Pat your self on the back and wait for your pull request to be reviewed and merged.
 
-## Updating Git
+Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
-Ensure the submodule is checked out to the correct tag, e.g:
-
-```
-cd git
-git checkout v2.11.1
-```
-
-The package scripts will look for this tag, so non-tagged builds are not
-currently supported. Committing this submodule change and publish a pull
-request to initiate the build scripts.
-
-## Changing how Git is built
-
-Refer to the build scripts under the `script` folder for how we are building Git for each platform:
-
- - [Windows](https://github.com/desktop/dugite-native/blob/master/script/build-win32.sh)
- - [macOS](https://github.com/desktop/dugite-native/blob/master/script/build-macos.sh)
- - [Ubuntu](https://github.com/desktop/dugite-native/blob/master/script/build-ubuntu.sh)
-
-Ideally we should be using the same flags wherever possible, but sometimes we
-need to do platform-specific things.
-
-Windows doesn't need to be built from source, however it should be updated in step with the other Git releases. When a new [Git for Windows](https://github.com/git-for-windows/git) release is made available, just update the
-`GIT_FOR_WINDOWS_URL` and `GIT_FOR_WINDOWS_CHECKSUM` variables in `.travis.yml`
-to use their MinGit build.
-
-## Updating Git LFS
-
-Packages are published for each platform from the [Git LFS](https://github.com/git-lfs/git-lfs)
-repository. These are defined as environment variables in the `.travis.yml` -
-update the `GIT_LFS_URL` and `GIT_LFS_CHECKSUM` for all platforms and commit
-the change.
+- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
+- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+- In your pull request description, provide as much detail as possible. This context helps the reviewer to understand the motivation for and impact of the change.
 
+## Resources
 
+- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
+- [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/)
+- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
+- [GitHub Help](https://help.github.com)

README.md

@@ -2,13 +2,6 @@
 
 [![Build Status](https://api.travis-ci.com/desktop/dugite-native.svg?token=vdtkHSqgzNMgfyZkfVbP&branch=master)](https://travis-ci.com/desktop/dugite-native)
 
-This repository contains the source and scripts for building a portable version
-of Git for various platforms that [`dugite`](https://github.com/desktop/dugite)
-supports.
-
-**Note:** this is not intended to installed by end users - [go here](https://git-scm.com/)
-to download Git for your operating system.
-
 ### What?
 
 This project is designed to build a version of Git which is optimized for
@@ -22,18 +15,38 @@ scripted usage in applications, and removes many non-core features:
  - no translation of error messages
  - no 32-bit support
 
-For some platforms, we can use upstream packages that can be consumed in a
-standalone way. [Git for Windows](https://git-for-windows.github.io), for example,
-offers a minimal environment called MinGit with each release that covers
-most of the above requirements.
-
 There are also additional customizations included in this toolchain:
 
  - Git-LFS
  - certificate bundle for Linux consumers
 
+**Note:** this is not intended to installed by end users - [go here](https://git-scm.com/)
+to download Git for your operating system.
+
+### Status
+
+This project is under active development for Git-related projects at GitHub. This will stabilize as this library gets more usage in production.
+
+### Roadmap
+
+It is expected that this toolchain will be updated as Git and it's other dependencies are updated, to ensure applications are running on the latest
+stable version of Git.
+
+Feel free to open issues or pull requests about fixes or optimizations we can incorporate
+into the packaging process. Refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) file for instructions and the [documentation](./docs/) sections for more information about the repository.
+
+Bugfixes and feature requests for Git should be discussied on the [Git mailing list](https://git.wiki.kernel.org/index.php/GitCommunity).
+
 ### Supported Platforms
 
  - Windows 7 and later
  - macOS 10.9 and up
  - Linux (tested on Ubuntu Precise/Trusty and Fedora 24)
+
+### Credits
+
+The [Git for Windows](https://git-for-windows.github.io) project already
+provides a minimal environment (called 'MinGit') with each release that covers
+most of the above requirements.
+
+[Travis](https://travis-ci.org/) provide the build infrastructure for compiling and packaging Git across all the necessary platforms.

docs/README.md

@@ -0,0 +1,5 @@
+# Documentation
+
+ - [Overview](./overview.md) - introduces how the repository and scripts work
+ - [Making Changes](./making-changes.md) - a deeper introduction in the scripts and how to contribute changes
+ - [Setup](./setup.md) - details about setting things up for local development

docs/making-changes.md

@@ -0,0 +1,53 @@
+# Making Changes
+
+To improve the `dugite-native` toolchain, just find the appropriate hook.
+
+## Update Git
+
+If you want to incorporate a new version of Git, first ensure the submodule is
+checked out to the correct tag, e.g:
+
+```
+cd git
+git checkout v2.11.1
+```
+
+The package scripts will look for this tag, so non-tagged builds are not
+currently supported. Commit this submodule change and publish a pull request
+to test the packaging changes.
+
+## Change how Git is built
+
+Refer to the build scripts under the `script` folder for how we are building
+Git for each platform:
+
+ - [Windows](https://github.com/desktop/dugite-native/blob/master/script/build-win32.sh)
+ - [macOS](https://github.com/desktop/dugite-native/blob/master/script/build-macos.sh)
+ - [Ubuntu](https://github.com/desktop/dugite-native/blob/master/script/build-ubuntu.sh)
+
+Ideally we should be using the same flags wherever possible, but sometimes we
+need to do platform-specific things.
+
+Windows doesn't need to be built from source, however it should be updated in
+step with the other Git releases. When a new [Git for Windows](https://github.com/git-for-windows/git)
+release is made available, just update the `GIT_FOR_WINDOWS_URL` and
+`GIT_FOR_WINDOWS_CHECKSUM` variables in `.travis.yml` to use their MinGit
+build.
+
+## Update Git LFS
+
+Packages are published for each platform from the [Git LFS](https://github.com/git-lfs/git-lfs)
+repository. These are defined as environment variables in the `.travis.yml` -
+update the `GIT_LFS_URL` and `GIT_LFS_CHECKSUM` for all platforms and commit
+the change.
+
+## Add a new component
+
+If there is some component you think should be incorporated into this package,
+please [open a new issue](https://github.com/desktop/dugite/issues/new) with
+as much detail as possible about what the package is and why you think it is
+valuable.
+
+If the maintainers agree that this is a worthy addition, you are
+then welcome to contribute a pull request to incorporate this. Note that this
+package is intended to be as lean as possible, so make a good case for it!

docs/OVERVIEW.md → docs/overview.md

@@ -29,7 +29,7 @@ is enough to fail the build process.
 Packaging is rather consistent for each platform, and mostly focuses on
 ensuring the right binaries are published and fingerprinted correctly.
 
-#### GitHub Release
+### GitHub Release
 
 When a tag is pushed to GitHub, Travis will detect this and start a new build.
 The artefacts from that build are then uploaded to GitHub, ready to use in a

docs/setup.md

@@ -0,0 +1,31 @@
+# Setup
+
+As these scripts are dependent on the OS you have setup, I've not spent much
+time testing things out about the local development experience. Please
+:thumbsup: [this issue](https://github.com/desktop/dugite-native/issues/26)
+if you encounter friction with running things locally and would like it to be
+easier.
+
+### Requirements
+
+As this project depends on the toolchain you have installed, you will also need access to the same operating system you wish to compile Git for. Currently we don't need to build from source on Windows, but for macOS we do need access to the XCode toolchain. You also need a bash environment to run these scripts.
+
+### Testing
+
+You should be able to emulate the behaviour of Travis by setting environment variables. For example, to package for macOS you could run this:
+
+```
+GIT_LFS_URL=https://github.com/git-lfs/git-lfs/releases/download/v2.0.0/git-lfs-darwin-amd64-2.0.0.tar.gz \
+GIT_LFS_CHECKSUM=fde18661baef286f0a942adf541527282cf8cd87b955690e10b60b621f9b1671 \
+script/build-macos.sh ./git /tmp/build/git/
+```
+
+**NOTE:** one potential way to tidy this up could be to have helper scripts read out the details of the `.travis.yml` file so you don't have to duplicate the work.
+
+For example, it could distill down to:
+
+```
+./test macOS /tmp/build/git
+```
+
+This would mean the contributor doesn't need to care about changes to how the pipeline works, and can focus on the behaviour of the scripts.