Skip to content

Contributing

Jump to bottom
Monica Wheeler edited this page May 12, 2021 · 12 revisions

Creating

To add new code or components, see the README files within docs/ folder and withinin each Package of the code base.

Coding conventions

See the links under Guielines in the Sidebar for coding conventions for HTMl, CSS, and JavaScript within our system.

Git structure

Read our current process for contributing through our version bumping process

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 contains the currently public and deployed version of our code; develop is generally where we base any new work. This allows us to batch together a set of code to later publish and deploy as a solitary merge to master. Read more here.
  2. Generally, work is performed in new feature branches off of develop and set up to merge into develop. Exceptions such as urgent bugfixes and documentation-only updates may be based off of and merged into master.
  3. Feature branches should follow Jira naming conventions if a Jira issue has been assigned. Otherwise, use the established naming format
  4. Rebase against your based branch (typically develop) 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 develop.

  1. Check out develop: git checkout develop
  2. Make sure you have the latest changes from develop with git pull --rebase origin develop
  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

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 develop branch — it creates a timeline/history on develop and eventually 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-lib 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-lib 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
  1. Rebase your branch on top of develop:
  • git checkout develop
  • git pull --rebase origin develop
  • git checkout abc-1234_some_feature_description
  • git rebase develop
  1. Resolve conflicts if necessary
  2. 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 develop 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 develop. 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 develop:
  • git checkout develop
  • git merge --no-ff abc-1234_some_feature_description
  • git push origin develop
  1. 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.)

Your Feature/Fix PR

  1. Describe change geared towards UXD reviewers

  2. Provide any viewing instructions for the change in sage-lib (docs or Storybook)

  3. Provide ranking of impact in kajabi-products and testing steps geared towards QA:

    • Describe if/how instances should be impacted imagining your QA as the audience.

    • Rankings include:

      • Breaking: includes breaking change that needs patch
      • High: affects many features or is a substantive change to functionality. Extra care should be taken.
      • Medium: moderate changes or used moderately
      • Low: little to no expected impact in kajabi-products: new component or new features on a component that do not touch on defaults.

    • Provide specific places to check that represent known variations of the component.

      • If no impact is expected still list a few examples that can verify this when practical
      • Consider instances outside your domain as well.
      • Should not need to provide all instances, but only those representative of the component's use or that demonstrate you didn't break anything!
      • Place checkboxes next to verifiable items to help QA track what has been validated.

      Samples:

      • (BREAKING) Changes to FeatureToggle require a patch in kajabi-products to adjust the configuration for links (to be included in version bump). However, current usage is under feature flag beta_features so should not affect otherwise. PR #17612 contains fixes to be merged afterwards.
      • (Medium) Adds LabelGroup and LabelSecondaryButton to assist composition in Labels. Should not have effect on existing labels. Ensure labels look same and function as they have to date:
        • Product outline editor (React): publish status dropdowns
        • Contact import bulk actions step (React): Tag selections that appear below dropdown
        • Settings > Domain (Rails): see Kajabi default is displaying as before
        • Offers (Rails): publish status label appears as expected
      • (Low) Add fullWidth modifier to React Button. Should have no effect on existing Buttons. Confirm that any buttons in the follow appear as expected:
        • New Contact import process
        • Product outline manager
      • (Low) New Transaction Card. No impact as this is a new component.

  4. Author of the PR should have tested the QA steps themselves with the bridge on, even across functional domains, getting assistance as needed.

  5. Ideally get 2 peers approval on PR.

  6. Merge into develop unless coordinated with others as a time-sensitive fix.

NOTE: If your PR introduces BREAKING changes to kajabi-products you should HOLD merging this PR in sage-lib until you've drafted and linked to a PR in kajabi-products that provides the fixes. (See the BREAKING example above). Later, once the version bump moves forward this fix branch can be added onto the kajabi-products version bump branch.

Thanks for using Sage!

Welcome

Conventions

Processes and Reference

Clone this wiki locally