a2974fa7fe
The readme is getting quite large, so in an effort to shorten it, the Git installation instructions (which have nothing to do with PowerShell, but are helpful for new users), are now in `CONTRIBUTING.md`. Thus, if someone is totally new to Git, they will be far more likely to review our contributing guidelines, and so read our rules and best practices. Cloning the source code was cleaned up so that initializing the submodules is done in a separate step. This simplifies the first step, making it more likely to succeed (and narrowing the possible failures).
4.1 KiB
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.
Installation
Windows
Install Git for Windows.
During the install process, choose these recommended settings:
- Use Git from the Windows Command Prompt
- Use OpenSSH
- Checkout Windows-style, commit Unix-style line endings
- Use Windows' default console window
- Enable file system caching
Linux
Install via the package manager:
sudo apt-get install git
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.
git config --global credential.helper store
Alternatively, on Windows, you can try the Git Credential Manager for Windows.
New to Git?
If you're new to Git, learn the following commands: checkout, branch,
pull, push, merge.
Use GitHub's Hello World to learn how to create a feature branch, commit changes, and issue a pull request.
The user name and email must be set in order to commit changes:
git config --global user.name "First Last"
git config --global user.email "alias@microsoft.com"
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.
Rebase and Fast-Forward Merge Pull Requests
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. If you are uncomfortable doing this, please ask @andschwa to 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
I highly recommend these configurations to help deal with whitespace, rebasing, and general use of Git.
Auto-corrects your command when it's sure (
statstostatus)
git config --global help.autoCorrect -1
Refuses to merge when pulling, and only pushes to branch with same name.
git config --global pull.ff only
git config --global push.default current
Shows shorter commit hashes and always shows reference names in the log.
git config --global log.abbrevCommit true
git config --global log.decorate short
Ignores whitespace changes and uses more information when merging.
git config --global apply.ignoreWhitespace change
git config --global rerere.enabled true
git config --global rerere.autoUpdate true
git config --global am.threeWay true