Originate guides – Git
These are recommendations. They should be followed in the absence of good and justifiable reasons for doing things differently.
GitHub user account
Make sure you have 2-factor authentication enabled. Your GitHub account is used to access many things, and it’s important to know that the changes really come from you, even if you work in open source.
Git
best practices
- Git flight rules
Branches
- One (or more)
- Refactorings and bug fixes should be in their own feature branches and reviewed separately.
- named as “[developer initials]-[feature-name]”, for example, kg-new-settings-page Feature branches are cut from
- and merged into
- development server The master branch matches
- what’s in production
- Other servers have long-lived branches that match them by name: the staging branch matches the staging
- If the project is integrated with a ticket tracking system, the feature branches must be named using the following convention: “[developer initials]-[ticket key]-[feature-name]”, for example, kg-OR-16-new-settings-page. Note that JIRA expects the ticket key to be uppercase.
feature branches per user story.
Feature branches are
the development branch Development branch matches
server, etc.
Commits
- Each commit in the parent branch must contain only one particular change
- Commit frequently during your work, whenever a dedicated change is made and the tests pass. Don’t rack up dozens of changes before you commit. Rather, get into the habit of doing one thing at a time, reviewing and engaging it when you’re done, and then doing the next one.
- Always review your work before committing it.
- Crush the commits in its entity branch, or perform a squash commit when merged into the main branch, so that it appears there as a single atomic confirmation.
- Write good confirmation messages: A 50-character digest written in imperative (“fix signup”) or as a brief summary of features (log out button), followed by an empty line, followed by an optional longer description.
.
Conflict resolution
Conflicts occur when two developers change the same line in the same file at the same time. To resolve them
,
- use git status to see which files have conflicts
- open the conflicting files in your editor, and resolve the conflicts. Be sure to consider that both sides of the conflict contain changes that occurred at the same time, so both changes must be present in the resolved code.
,
# Resolve conflicts in your text editor $ git add [path of resolved file] $ git rebase -continue
Pull requests
When you’re done with a feature, submit a pull request so it can be reviewed and merged into the development branch
.
Extraction requests are how we ensure quality and share knowledge. The goal is for everyone to hold each other to a high standard, for everyone to learn from each other, and to catch architectural and other errors before they reach the main branch. The tone should be constructive and positive.
Everyone
- can (and should) review everyone else’s pull requests.
- Refactorings should be reviewed by the technical lead or architect
- All comments given in a PR should be at least addressed, that is, if you do not want to do so, say why and reach an agreement with your reviewer on this topic. Getting a third opinion is a good option.
- Finding and pointing out problems in PRs is a good thing. Bonus points if you encounter problems in the senior code!
- You must tag reviewers in your pull request description (@username). This is especially important on larger projects because it helps people know which RP needs their attention.
- Every piece of code (backend, database changes, HTML, CSS) needs to be reviewed. You can use multiple reviewers for different types of code.
- Mark pull requests that should not be merged as “WIP” in the PR title (“WIP: New Configuration Page”).
- No feedback on a PR means that the review was not thorough enough. Getting feedback on your PR is good, it means you’re alive and learning. Learning never ends!
- Well-written code bases are reviewed in an iteration (a set of comments, a round of fixes, done). If your reviews usually take several rounds, try to be more thorough before submitting your PR.
- When a PR gets LGTMed (“looks good to me”), it will be merged by the author, and the feature branch must be removed from both the local machine and Github.
.
Here’s a checklist for reviewers:
Is each piece of code in the right place, i.e. model code in a model, driver logic in a controller,
- application-specific stub in a helper, generic stub in a library
- have a single responsibility
- all methods do one thing
- Are all classes/methods/variables named correctly so that the code is automatically described?
- Is everything as private as possible, i.e. no fields/methods that are not used externally are made public?
- Are all files within a reasonable size (less than 100 loc)?
- Are all methods less than 10 loc?
- Is there no law of demeter violations (providing complete objects to methods when all that is needed is the value of an attribute of them)?
- Is everything proven enough? Are things over-tested?
- Are there any obvious inefficiencies, such as performing a database query for each loop iteration, instead of using a more streamlined query that loads all the data at once?
- Spacing errors such as no empty line between methods or too many empty lines.
- There should be no commented code. The commented code should be deleted.
- There should be no debugging statements like “console.log” or similar.
? Do all classes
? Do
?
Is everything proven?
Split large branches
See our blog post on Refactoring Git branches
.
Fusion
If possible, do a squash combination. Advantages of squash mergers:
Git history contains only one
- clean commit per feature/bug fix Git history
- straight line of linear commits, rather than the typical spaghetti branch craze Git
- Bisect becomes a possibility again
- A git guilt doesn’t just tell you who wrote a line of code, but also why (i.e. the broader
- Confusing deviations during development are no longer visible in the final commit
- Each change provides the full context of the change (“user is set to null because of this feature”)
- /bug fixes as part of the release process: When a version breaks, we can leave broken features out and release them anyway
- Easier commit names: Name your development commits the way you want, and for final commit, copy and paste the ticket title and description
is a
context of a change)
Easier feature selection
Tools
The best Git tool is the command line. It’s easy to learn and use, and it makes the full power of Git available. In addition to the command line, it’s often helpful to have a visual representation of your Git tree and an interactive tool for organizing changes/making commits. Here are some tools used by Originate developers
: Git
Town command line
- : High-level command line interface for Git
