Note |
---|
TL;DR: many edX tools and scripts depend upon Git commit messages so it is important that we are consistent in our usage. |
Table of Contents
Table of Contents |
---|
Configuration
It is recommended that all developers run the following Git configuration commands:
Code Block |
---|
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:
Code Block |
---|
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.
Jira Legacy server JIRA (openedx.atlassian.net) serverId 13fd1930-5608-3aac-a5dd-21b934d3a4b4 key LEARNER-1696
- 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 50 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
- The first line of a commit message should be a title broken into
Example commit message:
No Format https://github.com/edx/edx-platform/commit/978e9fe656bb249237ba1ceea0ebec1aa0b06fa7
No Format Fix inline discussions to use cached static assets In production environments, the DiscussionXBlock was generating CSS and JS asset URLs that pointed to the unminified versions of those bundled assets. Due to our nginx rules, this would cause the assets to be served without the long expiration times, forcing the user's browser to constantly refetch these assets while browsing a course. [PERF-431]
- Why is this important?
- 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
- Here are a few blog posts that explain the rationale behind these rules:
- "What’s with the 50/72 rule?"
- "How to Write a Git Commit Message" "A Note About Git Commit Messages"
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.