130 lines
3.9 KiB
Markdown
130 lines
3.9 KiB
Markdown
Contributing to Project Magrathea
|
|
=================================
|
|
|
|
Rules
|
|
-----
|
|
|
|
**Do not commit code changes to the master branch!**
|
|
|
|
Don't forget to commit early and often!
|
|
|
|
Please add `[ci skip]` to commits that should be ignored by the CI systems
|
|
(e.g. changes to documentation).
|
|
|
|
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).
|
|
|
|
You do *not* necessarily need to have write permissions to the main
|
|
repositories, as you can also just [fork a repo][].
|
|
|
|
[fork a repo]: https://help.github.com/articles/fork-a-repo/
|
|
|
|
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.
|
|
|