Versioning code

Quartz is a long-lived product, people will come and go. Keeping a clean history of work is crucial to help future maintainers of Quartz understand what was done and why.

Start by reading and understanding the General version management principles, as they apply to all the assets of the system.

Learn Git basics before anything

Git is not trivial to get used to. Make sure to have a solid understanding of Git fundamentals to avoid creating a mess in your git repository and impede your teammate's work.

It's almost always possible to recover from mistakes, but it can be very painful and time-consuming.

Contribution lifecycle

Repository owners are in charge of maintaining a good level of security and quality in their code. Using GitHub forks and pull requests is the recommended way of keeping track of every change that is pushed to the code.

Making a change to your repository requires to follow specific steps in order.

1. Fork the repository in GitHub (when possible), and clone it locally.
2. Create a branch when you start working on a task
3. Commit changes to your branches.
4. Clean your commit history when you're ready to push your changes to the main repository
5. Push and check the CI runs successfully
6. Create a Pull Request to review and merge your changes back into the main repository.

Fork and clone the repository

When possible, fork the repository first. Read the GitHub forking guide to learn how to do so.

Forking is not available on all repositories

Unfortunately for now, the internal packages hosted in GitHub Enterprise Cloud can't be forked. This is a corporate restriction we're actively discussing with the GitHub administrators.

Whether or not you can fork the repository, you must clone it to get a local copy on your computer. There are several ways of doing so, as explained in the GitHub cloning documentation.

Create a branch

Whether or not you can fork a repository,when you start working on a task, create a new branch from next using a consistent branch naming convention. You can do so in several ways:

• let GitHub create the branch for you using the link provided in the Development section of the issue you're working on. Be careful to review the proposed settings and adjust the source branch as necessary.
• use a graphical Git client to make a new branch deriving from next.
• use the git CLI in your command prompt:

  git checkout next
  git checkout -b <type/the-new-branch-name>

Do we need branches if we can fork the repository?

Branches are still recommended withing your fork for several reasons:

• they keep your repository organized if you have to work on several topics in parallel (which will happen one day or another).
• they also keep the upstream repository cleaner by packing the commits of a specific release together in a branch. The main and next branches will only contain the merge commits that triggers releases by semantic-release (see Releasing code for more details on that).
• it makes cleaning your commit history easier and less prone to messing with the history of the next branch from the upstream repository.

Default branches

Quartz repositories come with two essential branches:

• the main branch, in which each commit is tied to a specific production release (ex: v1.2.3)
• the next branch, in which each commit is tied to a specific beta release (ex: 2.0.0-beta.3)

Don't make direct changes to the default branches

Always use temporary branches to isolate your changes and avoid accidentally releasing breaking changes (see below).

Commit changes to your branch

Your commits should follow the Conventional commits specification. Make sure to read and understand the Conventional commits section below.

Commit hooks

When you commit, custom Git hooks will ensure your message is valid and run linting on the staged files.

In the early stages, you may fall back to using the chore: <summary> commit pattern for quick, less formal commits. Use meaningful labels anyway to help you cleaning your history later.

For example:

• chore: update dependencies
• chore: draft Foo parsing
• chore: draft Foo linting
• chore: finish Foo linting
• chore: finish Foo parsing
• chore: chore: lint Foo in build

Don't overuse the chore commit type

Try to scope your commits to a clean set of related changes: is it a new feature, a fix, documentation, a routine clean-up, etc. With time, you will develop a good sense of using directly the correct commit types.

Conventional commits

We use the Conventional commits specification for that purpose. Make sure you understand it. Even if you never used it before, you will quickly get used to it and see the clarity and consistency it brings to project's history.

A typical commit message goes like this:

<type>[optional scope]: <description>

[optional body]

[optional footer]

where:

• <type> is a keyword (see table below) indicating the nature of the commit
• <description> starts with a lowercase infinitive verb and has to be short
• [optional scope] provides context in parenthesis
• [optional body] is a lengthier description of the change, supporting Markdown syntax (bullet lists, emphasis, etc.)
• [optional footer] is mostly used to describe breaking changes (see below).

Here are a few correct examples:

• Simplest commit: fix: make tooltip visible again

• With context: feat(button): show tooltip when label is truncated

• With description:

  feat(button): show tooltip when label is truncated
  
  Tooltip is shown when:
  - button has a fixed width
  - **and** label is too long
  - **and** the `overflow` option is set to `truncate`

Breaking changes

To indicate breaking changes, add an exclamation mark (!) just before the column (:), and document the impact of the change in the footer, starting with BREAKING CHANGE:. Like this:

feat(button)!: show tooltip when label is truncated

Tooltip is shown when:
- button has a fixed width
- **and** label is too long
- **and** the `overflow` option is set to `truncate`

BREAKING CHANGE: the `overflow` option is now a string
attribute instead of a boolean, accepting the
`visible` and `truncate` options.

Think carefully about breaking changes!

It's easy to overlook a change that could break backward compatibility for your consumers. Think carefully about that when crafting your commit message.

Common causes of breaking changes:

• removal/rename of options/features
• change of data format (input, output, configuration...)
• change of required parameters (e.g. something optional becomes required)
• change of behavior of an existing option/feature
• reordering of options

Commit types

The following table lists the commit types used by Quartz, their purpose, and how they impact version numbers and release notes generation:

Commit type	Purpose	Version increment	Included in release notes
feat	A new feature	Minor	✅ Yes
fix	A bug fix	Patch	✅ Yes
perf	A code change that improves performance	Patch	✅ Yes
revert	A previous change that was reverted	Major	✅ Yes
*!	Any type with BREAKING CHANGES	Major	✅ Yes
build	Changes that affect the build system	Ignored	🚫 No
ci	Changes to CI configuration	Ignored	🚫 No
docs	Documentation only changes	Ignored	🚫 No
refactor	A code change that neither fixes a bug nor adds a feature	Ignored	🚫 No
style	Changes that do not affect the meaning of the code (formatting, etc.)	Ignored	🚫 No
test	Adding missing tests or correcting existing tests	Ignored	🚫 No
chore	Other changes that don't modify source files. Don't overuse it!	Ignored	🚫 No

Use only the commit types from the above table

That list is used in Quartz's semantic-release preset. It impacts how version numbers are incremented and how the release notes are generated.

commit-msg hook

We use husky to install a commit-msg hook that will run commitlint to ensure the message follows that standard. commitlint is configured with a custom preset implementing the Quartz specific practices.

Clean commit history

We use semantic-release to handle the release process, which generates the release notes from your commit history. That's why it is crucial that you always review and clean your commit history before submitting your changes for review and release.

You can do so by using the Interactive Rebase Git feature, as described in the Rewriting History chapter from The Git book.

Tip

Some Git UI clients have nice visual interfaces for interactive rebasing (see this GitKraken tutorial for an example).

Be aware that using interactive rebase, you will most often have to force push your changes to the remote repository. That's why working in your branch avoids accidentally overwriting the commit history from the upstream repository.

Reminder

Your final commit history must follow the Conventional commits specification. See Conventional commits for guidance.

We could clean the history from the previous example by:

• Squashing together the draft/finish commit pairs
• Rewording the build commit to use the proper commit type. Also, our consumer's build may fail due to the added Foo syntax linting. We indicate that by adding an exclamation mark (!) after the commit type and describing the breaking changes in the commit's description (not shown here).

Which would result in the following history:

• chore: update dependencies
• feat: support the Foo syntax
• build!: add Foo syntax linting

Thanks to that clean history, when the owners release a version, semantic-release will automatically increment the major version number (because we indicated a breaking change) and generate clean release notes in the repository's CHANGELOG.md file:

# Change log

# @quartzds/my-package 2.0.0

## ⚠ BREAKING CHANGES

- The build now parses the Foo syntax

## ✨ Features

- Support the Foo syntax

An example release history

You can look at an example release history in the Releasing code page.

Push your branch and check the CI

To be discussed and updated

• where and how to push (fork or not)
• how to check the CI
• how to commit fixes: rewrite the commit history?

Create a Pull Request

Create a Pull Request when you're ready to merge your changes into the upstream repository:

The CI will first run checks on your branch, then the repository owners will review your PR.

Don't skip the Pull Request process to save time

Pull Requests exist to prevent adding debt to the project. As your team maturity grows, the PR process will shorten.

Adding changes to your PR

While the PR is open, if the owners request changes from you, you just have to push changes to your branch. GitHub will automatically re-run the checks and notify the owners of your update.

Once the repository owners approve your PR, they will first merge it into the next branch and create a beta release. You can then collect feedback from your early testers.

Your branch will be deleted

When a PR is merged, your branch will be automatically deleted. If that's not the case, you can safely delete it in your fork/local repository.

Adding changes after a beta release

Once a beta version has been released, you must create a new PR and start a new beta cycle to contribute additional changes.

Releasing to production

After releasing a beta version, if your early testers are happy with your changes, request the owners to release a production version.

Congratulations! 🎉

You contributed a clean set of changes to the legacy of the project!