Version-Control

Last edited 51 seconds ago by System Writer
Kanopi Studios uses Git to version control all project code and hosts distributed version control on Github. Alternative remote repository platforms may be used based on client project requirements, including BitBucket and GitLab.
We strive to structure our projects in a standardized way. Inherited support projects may not adhere to all structure standards; it is encouraged to bring these projects into alignment with the Kanopi standard structure as budget and timelines permit. New Build projects should follow these guidelines.

What Is Tracked In Version Control

custom code (e.g., themes, plugins, modules),
README files,
make files,
composer.json and composer.lock files,
package.json and package.lock files,
configuration, including deployment (i.e., CircleCI) and project setup (i.e., Docksal files),
linting, and
other system files

Example of items to gitignore:

mysql.sql (any db files)
uploads
local config files
vendor
node_modules
any large media files like videos

Resources:

Starter repository .gitignore examples:

Guidelines:

Include third-party code via package managers and do not version control.
PHP: Composer
Plugins: WPackagist
Compiled files (e.g., JS/CSS) should be built during deployment and not be committed to the project.
The canonical source for production code should exist on the branch named main.
The main branch should be protected so that merges cannot happen unless the code has been reviewed by at least one reviewer.
At Kanopi, we consider a standardized workflow a very important part of the development process. Utilizing an effective, consistent workflow ensures efficient collaboration and quicker project onboarding. For this reason, we use the following workflows company-wide for internal and client projects.

Branching

All projects will treat the main branch as the canonical source for live production code. Feature branches will branch off main and should always have main merged back into them before requesting peer code review and before deploying to any staging environments.
Branching Naming Conventions
We want a one-to-one relationship with tasks and tickets, which means branches should be small and encompass only the task at hand. If you are working on a sub-task or a feature with dependencies, use the parent task ID.
Task (feature, bug, or hotfix) / project management system + task ID - short description
Example branch naming:
feature/twXXXX-short-desc
bug/twXXXX-short-desc
hotfix/twXXXX-short-desc
Teamwork Task ID:
Teamwork ID
Common Project Management System abbreviations:
tw = Teamwork
ji = Jira
Special Cases:
WordPress plugin updates
Use the feature prefix with the year and month, e.g.: feature/tw{{task ID}}/plugin-{{YYYYMM}}
Guidelines:
All new development should occur on feature branches that branch off the default branch (main).
Use a new branch for every task/feature.
Review the project-level documentation and repository READMEs for project-specific workflows.
Contact the project Technical Lead if you have any questions on project branching requirements.
Regularly merge the remote main branch to your local main branch.
$ git checkout main
$ git pull [or] git fetch && git merge
Regularly delete your merged branches on both local and remote repositories.
The reviewer of the Pull Request on GitHub will delete the branch upon merging into the remote main branch. This can be configured to delete on merge automatically. Please contact #helpdesk to configure if it is not on your project.
When a Pull Request is approved, you are safe to delete the branch on your local machine:
## Delete a Local Branch in Git
$ git branch -d name-of-local-feature-branch

## Note: exercise caution when forcefully deleting a local branch with the following command. This will result in losing untracked work.
## -- delete --force a Local Branch in Git
git branch -D name-of-local-feature-branch
Complex Feature Branching
In some cases, a feature will be large enough to warrant multiple developers working on it at the same time. In order to test the feature as a cohesive unit and avoid merge conflicts when pushing to the staging and main branches, it is recommended to create a parent feature branch to act as a staging area.
Branch from the main branch to create the parent feature branch and then, as necessary,
Create child feature branches from the parent feature branch for distinct items of work.
When child branch tasks are complete, merge them back to the parent feature branch.
To pull work from main:
Merge main into the parent feature branch, then
Merge the parent feature branch into the individual child feature branches.
When all work has been merged back into the parent feature branch:
The parent feature branch can then be merged into the staging or main branches as an entire unit of work.
Complex Merge Strategy Diagram

Commits

Commits should be small and independent items of work, containing changes limited to a distinct idea. Distinct commits are essential in keeping features separate, pushing specific features forward, or reversing or rolling back code if necessary.
Commit Message Format
Each commit message consists of a brief summary and optional description.
1. Brief Summary
The first line of a commit message is a brief summary of the changeset, describing the expected result of the change or what is done to affect the change.
$ git log --oneline -5

# fca8925 Update commit message best practices
# 19188a0 Add a note about autoloading transients
# 9630552 Fix a typo in PHP.md
# 2309e04 Remove extra markdown header hash
# 5cd2604 Add h3 and h4 styling
2. Description (optional)
Separated from the summary by a blank line is the longer description. It is optional and includes more details about the commit and any repercussions for developers. It may include links to the related issue, side effects, other solutions that were considered, or a backstory. A longer description may be useful during the merge of a feature branch, for example.
Example Commit Messages:
$ git commit -m "feat: Add an #Element.matches polyfill to support old IE"

$ git log
commit 11112222333344444
Author: Your Name you@example.com
Date: Fri Jan 06 20:18:15 2023

feat: Add an #Element.matches polyfill to support old IE
$ git commit -m "fix: ensure post type is set before querying"
-m "Exits Relevanssi search results filter by type if the post type query variable is not available. Corrects Missing index notice."

$ git log
commit 11112222333344444
Author: Your Name you@example.com
Date: Fri Jan 06 20:18:15 2023

fix: ensure post type is set before querying

Exits Relevanssi search results filter by type if the post type query variable is not available.
Corrects Missing index notice.
Guidelines
A brief summary is always required.
Aim for around 50 characters or less, always stopping at 70.
The high visibility of the first line makes it critical to craft something that is as descriptive as possible within space limits.
The summary may be prefixed with a commit type that easily identifies the focus of the change. Common commit types include:
build: Changes that affect the build system or external dependencies (example scopes: gulp, webpack, npm)
ci: Changes to our CI configuration files and scripts
docs: Documentation only changes
feat: A new feature
fix: A bug fix
perf: A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
test: Adding missing tests or correcting existing tests
plugin: Updating or adding a new plugin or module
standards: Formatting changes resulting from applying coding standards (e.g., phpcs, phpcbf)
(source: )

Pull Request Process

Developer Responsibilities
It’s an important part of controlling change management that we ensure that there is some separation of responsibilities in the code review process. Our preferred division of responsibilities is as follows.
PR creation - Developer
Resolving merge conflict - Developer
Code review - Technical Lead or Peer Developer
Merging into the main branch - Technical Lead or Developer*
Change implementation - Developer
Deployment - Technical Lead or Developer*
*Not all projects have a Technical Lead. Any project developer at the request of a Project Manager or Technical Lead may assume these responsibilities.
Before Creating a Pull Request
Merge the remote main branch into your local feature branch and resolve any conflicts.
## Pull the latest version of the remote main branch
$ git checkout main
$ git pull

## Merge main into your local branch
$ git checkout name-of-local-feature-branch
$ git merge main

## Push feature branch up to remote repo
$ git push origin name-of-local-feature-branch
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.