vendure/CONTRIBUTING.md

Contribution Guidelines

Hi! Thank you for taking the time to contribute to Vendure!

In order to make the best use of both your time and that of the Vendure maintainers, please follow the guidelines in this document.

Table of Contents

• Branches
• Bug fixes
• New features
• Commit message format
• Setting up the dev environment
• Suggested contribution workflow
• Contributing to the documentation
• Contributing to the Admin UI translations
• Where to get help
• Contributor License Agreement
• Issue Triage Guidelines

Branches

There are 3 important branches to know about:

• master - the default branch
• minor - a branch for commits which introduce new features which would go in the next SemVer minor release.
• major - a branch for commits which introduce breaking changes which would go in the next SemVer major release.

Bug fixes should go directly to the master branch, from which new patch releases will be made regularly. Periodically, the master branch will be merged into the minor and major branches.

Bug fixes

If you would like to contribute a bug fix, please first create an issue detailing the bug, and indicate that you intend to fix it. When creating commits, please follow the commit message format below.

New features

Similarly, please create a feature request issue detailing the functionality you intend to add, and state that you would like to implement it. When creating commits, please follow the commit message format below. Submit new feature pull requests to the minor branch.

When adding new public APIs to support your new feature, add a @since 1.2.0 tag (where "1.2.0" corresponds to what will be the next minor version) to the doc block. This will let readers of the documentation know the version in which the API was introduced. See the docs readme for more details on the valid docs tags.

/**
 * @description
 * Sets the value of the new API thing.
 *
 * @since 1.2.0
 */
myNewApi: number;

Commit message format

This repo uses Conventional Commits.

type(scope): Message in present tense

type may be one of:

• feat (new feature)
• fix (bug fix)
• docs (changes to documentation)
• perf (performance improvements)
• style (formatting, missing semi colons, etc; no code change)
• refactor (refactoring production code)
• test (adding missing tests, refactoring tests; no production code change)
• chore (updating build tasks etc; no production code change)

scope indicates the package affected by the commit:

• admin-ui
• admin-ui-plugin
• asset-server-plugin
• common
• core
• create
• email-plugin
• etc.

If a commit affects more than one package, separate them with a comma:

fix(core,common): Fix the thing

If a commit applies to no particular package (e.g. a tooling change in the root package.json), the scope can be omitted.

Breaking Changes

If your contribution includes any breaking changes (including any changes to the DB schema; backwards-incompatible changes to the GraphQL APIs or VendureConfig; backwards-incompatible changes to current behavior), please include a BREAKING CHANGE section in your commit message as per the Conventional Commits specification.

Please also make your pull request against the major branch rather than master in the case of breaking changes.

Example:

feat(core): Add new field to Customer

Relates to #123. This commit adds the "foo" field to the Custom entity.

BREAKING CHANGE: A DB migration will be required in order to add the new "foo" field to the customer table.

Linting

Commit messages are linted on commit, so you'll know if your message is not quite right.

Setting up the dev environment

After cloning the Vendure repo, please refer to the Development guide in the README for instructions on setting up your local development environment.

Suggested contribution workflow

Creating a fork:

Start by creating a fork of the repository. This can be done by navigating to our repository and clicking on the fork button. This creates your own copy under your GitHub account. We recommend keeping "vendure" as the name of the fork.

Cloning locally:

Run the following commands to create a local clone of the repository files, where you can safely develop and test out your changes:

git clone https://github.com/YOUR-USERNAME/vendure.git
cd vendure

Add the Vendure repository as the upstream remote to your clone:

git remote add upstream https://github.com/vendure-ecommerce/vendure.git

This lets you pull updates from the original repository directly to your local clone.

Staying up to date

[!TIP] It is a good idea to regularly update your local and forked repositories. This keeps your development environment synchronised and minimizes potential merge conflicts when contributing.

Here is GitHub's official guide on keeping your forks synced.

There are three main ways to keep your fork synchronized:

Option 1: Using GitHub's Web Interface

Navigate to your fork's GitHub page and click the Sync fork button.

Option 2: Using GitHub CLI

GitHub offers a handy open-source CLI tool - GitHub CLI - which allows you to sync your branch directly in your terminal:

gh repo sync

Option 3: Using Git Commands

If you prefer using git commands, which can be more robust in some circumstances:

First, fetch the latest changes:

git fetch upstream
git checkout master

Now you're on the master branch of your local repository, and Git "knows" whether there are differences between your master branch and the upstream branch.

Then, update your local and forked remote repositories:

git merge upstream/master
git push origin master

---

Create a new branch

This is where you can start implementing your changes:

git checkout -b your-new-branch

Developing

Follow our development guide to make sure you have a properly set up development environment.

After implementing your changes, stage the changes and commit them. Refer to the Commit message format

git add .
git commit -m "type(scope): Message in present tense"

Creating a pull request

[!TIP] Now would be a good time to update your local and remote repositories.

Prepare Your Branch

Make sure you have your new branch checked out and merge the latest changes from your up-to-date master branch:

git checkout your-new-branch
git merge master

Push Your Changes

Push your updated branch to your forked repository:

git push origin your-new-branch

Create Your Pull Request

You can now create a pull request! Choose one of the following methods:

Option A: Using GitHub CLI

If you have the GitHub CLI installed, run:

gh pr create

and follow the prompts - this will automatically use our pull request template.

Option B: Using GitHub Web Interface

Navigate to your forked repository on GitHub and create a pull request from there using the web interface.

Well done! Now comes our part: we will review your pull request and either merge it or provide you with feedback on what we would like to see changed.

---

Contributing to the documentation

For our documentation, we use Docusaurus.

After setting up your development environment, navigate to the docs directory and start the docusaurus server:

cd docs
npm run start

this will output a URL where you can preview your changes.

You can find all of our documentation built by docusaurus in these directories:

docs/docs
├── guides
├── reference // only contains generated documentation
└── user-guide

[!NOTE] Files in the reference directory are auto-generated. To edit reference documentation, modify the JSDoc comments in the source code and run npm run docs:build from the project root directory.

Contributing to the Admin UI translations

If you wish to contribute translations of the Admin UI into another language (or improve an existing set of translations), please see the Localization guide in the admin-ui package.

Where to get help

We have an active discord community, join us there and ask away! Vendure Discord

Read the documentation - Our comprehensive documentation covers everything you need to know about Vendure. It also includes guides and references for the tools that we use.

In case your pull request doesn't meet our requirements, we're here to help! We'll provide thorough reviews with clear guidance on how to get your contribution merged.

Contributor License Agreement

All contributors are required to agree to the Contributor License Agreement before their contributions can be merged.

This is done via an automation bot which will prompt you to sign the CLA when you open a pull request.

Issue Triage Guidelines

This section is meant for maintainers to help triage issues.

Quality Control

• Does the issue have a clear title and description?
• Was the issue template followed and is all required info available?
• If it's a bug report, are there clear steps to reproduce?

If any of the above are missing:

• Add a relevant blue label (e.g., needs reproduction, missing info)
• Comment to ask the reporter to supply the missing information

Check for Duplicates

Search to see if the issue is already reported or resolved. If it is a duplicate, close the issue with a message like Duplicate of #123.

Label the Issue

• Set an Issue Type: bug, feature or task
• Package: label with relevant package/component
• Assign a Priority Label if possible

Stale Issues

Issues that need more information should be closed after 1 month of inactivity.