142 lines
4.6 KiB
Markdown
142 lines
4.6 KiB
Markdown
Contributing to Project Magrathea
|
|
=================================
|
|
|
|
Rules
|
|
-----
|
|
|
|
**Do not commit code changes to the master branch!**
|
|
|
|
**Read the documentation on [submodules][]!**
|
|
|
|
**Do not commit submodule updates accidentally!**
|
|
|
|
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
|
|
|
|
[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
|
|
[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
|
|
--------
|
|
|
|
* 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 super-project and all [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/
|
|
|
|
Rebase and Fast-Forward Merge Pull Requests in Submodules
|
|
---------------------------------------------------------
|
|
|
|
*This is not necessary in the superproject, only submodules!*
|
|
|
|
Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
|
|
extra merge commit will always be created. This can be especially
|
|
annoying when trying to commit updates to submodules. Therefore our
|
|
policy is to merge using the Git CLI after approval, with a rebase
|
|
onto master to enable a fast-forward merge.
|
|
|
|
Submodules
|
|
----------
|
|
|
|
This repository is a superproject with a half-dozen [submodules][].
|
|
**DO NOT** commit updates unless absolutely necessary. When submodules
|
|
must be updated, a separate Pull Request must be submitted, reviewed,
|
|
and merged before updating the superproject. When committing submodule
|
|
updates, ensure no other changes are in the same commit. Submodule
|
|
bumps may be included in feature branches for ease of work, but the
|
|
update must be independently approved before merging into master.
|
|
|
|
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
|
|
```
|