Working with our codebase

We follow the rules and guidelines established in the Kajabi Git and GitHub documentation when working on bugs and feature requests.

In general, the main points are:

1. master is the primary development branch and source of truth.
2. All work is performed in new feature branches off of master.
3. Feature branches should follow Jira naming conventions if a Jira issue has been assigned. Otherwise, use the established naming format
4. Rebase master onto your feature branch as development time extends. This will keep your branch current when it comes time to merge.

---

NOTE: These instructions are intended for use from the command line (we recommend iTerm), though many of these flows can also be performed with a standalone GUI client such as GitHub Desktop, SourceTree, or even with certain code editors, if necessary. We recommend using the command line before moving to a GUI, as there are nuances to certain commands that can be glossed over or confusing with a GUI — for example, rebasing.

If you aren't comfortable with git or some of these commands, don't hesitate to ask others for assistance!

Creating branches

Base your feature branch off of master.

1. Check out master: git checkout master
2. Make sure you have the latest changes from master with git pull --rebase origin master
3. Create a new branch using the Jira branch naming conventions if in Jira. This will auto-link associated branches and PRs in Jira. If a Jira issue is not available or does not apply, create the branch using the standard Kajabi branch naming convention.

Jira branch naming conventions

Branch names for Jira follow the pattern ISSUE-123_some_feature_description, where:

• ISSUE-123: the issue key/id, for example SELL-300
• some_feature_description: a brief description of the update or feature

Kajabi branch naming conventions

Standard Kajabi branch names follow the pattern abc-1234_some_feature_description, where:

• abc: your initials
• 1234: the issue number for the feature on GitHub (if applicable)
• some_feature_description: a brief description of the update or feature

Issues

We strongly recommend beginning any development work from a new or existing Issue.

One method to do so is to convert an Issue to a Pull Request (PR) using hub. This allows you to consolidate the Issue and PR in one location for simplified tracking and documentation, with the small but notable disadvantage of being a non-reversable process.

Alternatively, you can manually create a Pull Request, referencing the Issue # in the PR's description to link them together. This has the benefit of separated tracking, in the rare case work in your branch is dropped or becomes stale. The disadvantage here being the need to maintain and update both the Issue and PR during the work cycle.

Pull Requests and merging

General guidelines

• Keep Pull Requests small. Large PRs, while sometimes unavoidable, are more difficult and time consuming to review than smaller PRs. Whenever possible, try to avoid PRs longer than 300 lines. This makes reviewing easier, less time consuming, and more enjoyable for everyone.
• Aim to open new PRs soon after your first commit. This helps ensure that other developers are not duplicating work in a different branch and brings visibility to potential blockers.

The following flows should be used for all new work. Doing so prevents other features from being mingled with your own in the master branch — it creates a timeline/history on master that is easier to digest when tracking a feature's commits.

Create a pull request

1. git push -u origin abc-1234_some_feature_description will push your local branch to GitHub
2. In the Sage GitHub repository, you should now see your branch listed in a banner near the top of the page
   • If you plan to follow the recommended flow of converting Issues to Pull Requests, skip the remaining instructions here, and proceed to that section to convert the Issue.
   • To manually create a PR, In the Sage GitHub repository, click the "Compare & pull request" button in the banner. A new window will open for a PR with your branch.
3. Fill out the description and associated metadata such as Labels
4. If not already set, add yourself as the assignee
5. Link the PR to the Issue using one of the automatic GitHub keywords. This will close any associated issues once your PR has merged
6. In the "Create Pull Request" button, there should be a dropdown arrow, which reveals a menu. Select the option "Create Draft Pull Request", which will indicate a work-in-progress PR

Converting Issues to Pull Requests

Be aware that this conversion process is one-way, meaning you cannot convert the PR back to an Issue afterwards.

1. Install hub
2. git push -u origin abc-1234_some_feature_description to push your local branch to GitHub
3. Convert an Issue with a specified <issue number> into a draft PR by using the command: hub pull-request -d -i <issue number>.

Getting your branch ready for review

1. Push to GitHub so you can request code review:

• git push -u origin ab-1234_some_feature_description

2. Rebase your branch on top of master:

• git checkout master
• git pull --rebase origin master
• git checkout abc-1234_some_feature_description
• git rebase master

3. Resolve conflicts if necessary
4. Push your feature branch back up to GitHub: git push --force

If your PR is in draft mode, remember to mark it as ready for review to reviewers will receive a request.

Your PR is approved and ready to merge

Now that your PR has received approval from one or more team members, nice work! You're ready to merge into the master branch. Follow the steps below to make sure the process goes smoothly.

1. In the time since your PR was in review, there may have been changes to master. Follow all steps in "Getting your branch ready for review" above to make sure your branch is in sync with the latest updates.
2. Merge your work into master:

• git checkout master
• git merge --no-ff abc-1234_some_feature_description
• git push origin master

3. Delete local and remote feature branches when you are ready

• git branch -d abc-1234_some_feature_description
• git push --delete origin abc-1234_some_feature_description If you receive the error unable to delete 'branch-name': remote ref does not exist, GitHub's delete-merged-branch bot has done this for you automatically.)