Table of Contents

Configuration

It is recommended that all developers run the following Git configuration commands:

git config --global --add branch.autosetupmerge true
git config --global --add branch.autosetuprebase always
git config --global --add push.default simple

Git has an issue with files containing unicode characters in their file name on any system using HFS+ filesystem. If you use a Mac and experience an untracked file immediately upon cloning the edx-platform repo, try running the following configuration command:

git config --global core.precomposeunicode false

Branches

When creating your own branches in shared repos, name then with your GitHub username as a prefix, separated by a slash: <username>/<description>

Even better is to use a personal fork: Working with Personal Forks.  Over time, these will become more and more important.

Commit Messages

• Many edX tools and scripts depend upon consistency in Git commit messages
  • Many tools including GitHub assume the presence of a short title
  • Release scripts and others can extract the ticket numbers to include in a list of commits
  • JIRA links tickets to any commits that include that ticket's number
    • e.g. 
• Commit messages should follow a regular format based on Conventional Commits.  
  • The first line of a commit message should be a title broken into type: subject in 70 characters or less
  • Further comments should be paragraphs wrapped to 72 characters
  • Include the JIRA ticket number on its own line to be picked up by scripts
  • If it is a breaking change, there should be a BREAKING CHANGE: footer
  • Read OEP 0051 for type descriptions and full details

• Example commit message:

  build: handle private.txt files properly The requirements/edx/private.txt file is for dev's own private package needs. There are two installation mechanisms in edx-platform, and neither handled the file properly: - `paver install_prereqs` had the wrong file name. The file was moved almost three years ago, and paver wasn't kept up. - `make requirements` used `private.*` which included private.in, which pip-sync balks at. Fixes: BOM-2345

  
  

Squashing commits

• Squash commits (as appropriate) before requesting a review.
• Do not squash commits once a review has started, to aid reviewers.
• Squash commits after the review, before merging a PR.

See Also

• Intro to Git
• Git Rebase HOWTO
• GitHub Reviewing for Non-GitHub Users