Contributing to Project Magrathea
=================================

Rules
-----

**Do not commit code changes to the master branch!**

Don't forget to commit early and often!

All pull requests **must** pass both CI systems before they will be approved.

Write *good* commit messages. Follow Tim Pope's [guidelines][]:

* The first line *must* be a short, capitalized summary
* The second line *must* be blank
* The rest should be a wrapped, detailed explanation of the what and why
* The tone should be imperative

[guidelines]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

New to Git?
-----------

- [Git Basics](../docs/git/basics.md): install and getting started.
- [Git for sd users](../docs/git/source-depot.md): a handy reference
  document for people familiar with `sd`.
- [Commit process](../docs/git/committing.md): step-by-step commit guide
  with all gory details.

Authentication
--------------

If you do not have a preferred method of authentication, enable the storage
credential helper, which will cache your credentials in plaintext on your
system, so use a [token][].

```sh
git config --global credential.helper store
```

Alternatively, on Windows, you can try the
[Git Credential Manager for Windows][manager].

[token]: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
[manager]: https://github.com/Microsoft/Git-Credential-Manager-for-Windows

Microsoft employees
-------------------

Microsoft employees should follow Microsoft open source [guidelinces][MS-OSS-Hub].

Particularly:

* [Join][MS-OSS-Hub] Microsoft GitHub organization.
* Use your `alias@microsoft.com` for commit messages email. 
* Enable [2 factor authentication][].

[MS-OSS-Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service
[2 factor authentication]: https://github.com/blog/1614-two-factor-authentication

[Branches](../docs/workflow/branches.md)
-------------------------------------

* Checkout a new local branch for every change you want to make (bugfix, feature).
* Use `alias/feature-name` pattern.
* Use lowercase-with-dashes for naming.
* Use same branch name in superproject and all [submodules][].

[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules

Permissions
-----------

If you have difficulty in pushing your changes, there is a high probability that
you actually don't have permissions.

Be sure that you have write access to corresponding repo (remember that
submodules have their own privilege).

Your should push to this repository instead of a fork so that the CI system can
provide credentials to your pull request. If you make a pull request from a
fork, the CI *will* fail.

Recommended Git configurations
------------------------------

We highly recommend these configurations to help deal with whitespace,
rebasing, and general use of Git.

> Auto-corrects your command when it's sure (`stats` to `status`)
```sh
git config --global help.autoCorrect -1
```

> Refuses to merge when pulling, and only pushes to branch with same name.
```sh
git config --global pull.ff only
git config --global push.default current
```

> Shows shorter commit hashes and always shows reference names in the log.
```sh
git config --global log.abbrevCommit true
git config --global log.decorate short
```

> Ignores whitespace changes and uses more information when merging.
```sh
git config --global apply.ignoreWhitespace change
git config --global rerere.enabled true
git config --global rerere.autoUpdate true
git config --global am.threeWay true
```

[Mapping](../docs/workflow/mapping.md)
-----------------------------------

Learn about new files locations in PowerShell/PowerShell.

[Resources](../docs/workflow/resources.md)
---------------------------------------

Learn how to work with string resources in `.resx` files.