|
|
@@ -6,182 +6,262 @@ In order to make the best use of both your time and that of the Vendure maintain
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
|
-- [Branches](#branches)
|
|
|
-- [Bug fixes](#bug-fixes)
|
|
|
-- [New features](#new-features)
|
|
|
-- [Commit message format](#commit-message-format)
|
|
|
+- [Getting Started](#getting-started)
|
|
|
- [Setting up the dev environment](#setting-up-the-dev-environment)
|
|
|
-- [Suggested contribution workflow](#suggested-contribution-workflow)
|
|
|
-- [Contributing to the documentation](#contributing-to-the-documentation)
|
|
|
-- [Contributing to the Admin UI translations](#contributing-to-the-admin-ui-translations)
|
|
|
-- [Where to get help](#where-to-get-help)
|
|
|
-- [Contributor License Agreement](#contributor-license-agreement)
|
|
|
-- [Issue Triage Guidelines](#issue-triage-guidelines)
|
|
|
+- [Development Workflow](#development-workflow)
|
|
|
+- [Contribution Guidelines](#contribution-guidelines)
|
|
|
+ - [Branches](#branches)
|
|
|
+ - [Bug fixes](#bug-fixes)
|
|
|
+ - [New features](#new-features)
|
|
|
+ - [Commit message format](#commit-message-format)
|
|
|
+- [Technical Standards](#advanced-topics)
|
|
|
+ - [Code Generation](#code-generation)
|
|
|
+ - [Testing](#testing)
|
|
|
+ - [Release Process](#release-process)
|
|
|
+- [Specific Contributions](#specific-contributions)
|
|
|
+ - [Contributing to the documentation](#contributing-to-the-documentation)
|
|
|
+ - [Contributing to the Admin UI translations](#contributing-to-the-admin-ui-translations)
|
|
|
+- [Help & Support](#help--support)
|
|
|
+ - [Where to get help](#where-to-get-help)
|
|
|
+ - [Contributor License Agreement](#contributor-license-agreement)
|
|
|
+ - [Issue Triage Guidelines](#issue-triage-guidelines)
|
|
|
+
|
|
|
+## Getting Started
|
|
|
+
|
|
|
+### Creating a fork
|
|
|
|
|
|
-## Branches
|
|
|
+Start by creating a fork of the repository. This can be done by navigating to our [repository](https://github.com/vendure-ecommerce/vendure) 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.
|
|
|
|
|
|
-There are 3 important branches to know about:
|
|
|
+### Cloning locally
|
|
|
|
|
|
-* `master` - the default branch
|
|
|
-* `minor` - a branch for commits which introduce new features which would go in the next [SemVer minor](https://semver.org/) release.
|
|
|
-* `major` - a branch for commits which introduce breaking changes which would go in the next [SemVer major](https://semver.org/) release.
|
|
|
+Run the following commands to create a local clone of the repository files, where you can safely develop and test out your changes:
|
|
|
|
|
|
-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.
|
|
|
+```bash
|
|
|
+git clone https://github.com/YOUR-USERNAME/vendure.git
|
|
|
+cd vendure
|
|
|
+```
|
|
|
|
|
|
-## Bug fixes
|
|
|
+Add the [Vendure repository](https://github.com/vendure-ecommerce/vendure) as the upstream remote to your clone:
|
|
|
|
|
|
-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.
|
|
|
+```bash
|
|
|
+git remote add upstream https://github.com/vendure-ecommerce/vendure.git
|
|
|
+```
|
|
|
|
|
|
-## New features
|
|
|
+This lets you pull updates from the original repository directly to your local clone.
|
|
|
|
|
|
-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.
|
|
|
+### Staying up to date
|
|
|
|
|
|
-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](./docs/README.md) for more details on the valid docs tags.
|
|
|
+> [!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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) on keeping your forks synced.
|
|
|
|
|
|
-```TypeScript
|
|
|
-/**
|
|
|
- * @description
|
|
|
- * Sets the value of the new API thing.
|
|
|
- *
|
|
|
- * @since 1.2.0
|
|
|
- */
|
|
|
-myNewApi: number;
|
|
|
-```
|
|
|
+There are **three main ways** to keep your fork synchronized:
|
|
|
|
|
|
-## Commit message format
|
|
|
+#### Option 1: Using GitHub's Web Interface
|
|
|
|
|
|
-This repo uses [Conventional Commits](https://www.conventionalcommits.org).
|
|
|
+Navigate to your fork's GitHub page and click the `Sync fork` button.
|
|
|
|
|
|
-```
|
|
|
-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)
|
|
|
+#### Option 2: Using GitHub CLI
|
|
|
|
|
|
-`scope` indicates the package affected by the commit:
|
|
|
+GitHub offers a handy open-source CLI tool - [GitHub CLI](https://cli.github.com/) - which allows you to sync your branch directly in your terminal:
|
|
|
|
|
|
-* admin-ui
|
|
|
-* admin-ui-plugin
|
|
|
-* asset-server-plugin
|
|
|
-* common
|
|
|
-* core
|
|
|
-* create
|
|
|
-* email-plugin
|
|
|
-* etc.
|
|
|
+```bash
|
|
|
+gh repo sync
|
|
|
+```
|
|
|
|
|
|
-If a commit affects more than one package, separate them with a comma:
|
|
|
+#### Option 3: Using Git Commands
|
|
|
+
|
|
|
+If you prefer using `git` commands, which can be more robust in some circumstances:
|
|
|
|
|
|
+**First, fetch the latest changes:**
|
|
|
+```bash
|
|
|
+git fetch upstream
|
|
|
+git checkout master
|
|
|
```
|
|
|
-fix(core,common): Fix the thing
|
|
|
+
|
|
|
+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:**
|
|
|
+```bash
|
|
|
+git merge upstream/master
|
|
|
+git push origin master
|
|
|
```
|
|
|
|
|
|
-If a commit applies to no particular package (e.g. a tooling change in the root package.json), the scope can be omitted.
|
|
|
+## Setting up the dev environment
|
|
|
|
|
|
-#### Breaking Changes
|
|
|
+> [!IMPORTANT]
|
|
|
+> The following instructions are for those who want to develop the Vendure core framework or plugins (e.g. if you intend to make a pull request). For instructions on how to build a project _using_ Vendure, please see the [Getting Started guide](https://docs.vendure.io/guides/getting-started/installation/).
|
|
|
|
|
|
-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](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-both-and-breaking-change-footer).
|
|
|
+### 1. Install top-level dependencies
|
|
|
|
|
|
-Please also make your pull request against the `major` branch rather than `master` in the case of breaking changes.
|
|
|
+`npm install`
|
|
|
|
|
|
-Example:
|
|
|
+The root directory has a `package.json` which contains build-related dependencies for tasks including:
|
|
|
|
|
|
-```
|
|
|
-feat(core): Add new field to Customer
|
|
|
+- Building & deploying the docs
|
|
|
+- Generating TypeScript types from the GraphQL schema
|
|
|
+- Linting, formatting & testing tasks to run on git commit & push
|
|
|
|
|
|
-Relates to #123. This commit adds the "foo" field to the Custom entity.
|
|
|
+### 2. Build all packages
|
|
|
|
|
|
-BREAKING CHANGE: A DB migration will be required in order to add the new "foo" field to the customer table.
|
|
|
-```
|
|
|
+`npm run build`
|
|
|
|
|
|
-#### Linting
|
|
|
+Packages must be built (i.e. TypeScript compiled, Admin UI app built, certain assets copied etc.) before being used.
|
|
|
|
|
|
-Commit messages are linted on commit, so you'll know if your message is not quite right.
|
|
|
+Note that this can take a few minutes.
|
|
|
|
|
|
-## Setting up the dev environment
|
|
|
+### 3. Start the docker containers
|
|
|
|
|
|
-After [cloning the Vendure repo](#cloning-locally), please refer to the [Development guide](https://github.com/vendure-ecommerce/vendure/blob/master/README.md#development) in the README for instructions on setting up your local development environment.
|
|
|
+All the necessary infrastructure is defined in the root [docker-compose.yml](./docker-compose.yml) file. At a minimum,
|
|
|
+you will need to start a database, for example:
|
|
|
|
|
|
-## Suggested contribution workflow
|
|
|
+```bash
|
|
|
+docker-compose up -d mariadb
|
|
|
+```
|
|
|
|
|
|
-### Creating a fork:
|
|
|
+MariaDB/MySQL is the default that will be used by the dev server if you don't explicitly set the `DB` environment variable.
|
|
|
|
|
|
-Start by creating a fork of the repository. This can be done by navigating to our [repository](https://github.com/vendure-ecommerce/vendure) 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.
|
|
|
+If for example you are doing development on the Elasticsearch plugin, you will also need to start the Elasticsearch container:
|
|
|
|
|
|
-### 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:
|
|
|
+```bash
|
|
|
+docker-compose up -d elasticsearch
|
|
|
+```
|
|
|
+
|
|
|
+### 4. Populate test data
|
|
|
+
|
|
|
+Vendure uses [TypeORM](http://typeorm.io) and officially supports **MySQL**, **MariaDB**, **PostgreSQL**, and **SQLite**.
|
|
|
+
|
|
|
+The first step is to populate the dev server with some test data:
|
|
|
|
|
|
```bash
|
|
|
-git clone https://github.com/YOUR-USERNAME/vendure.git
|
|
|
-cd vendure
|
|
|
+cd packages/dev-server
|
|
|
+npm run populate
|
|
|
```
|
|
|
|
|
|
-Add the [Vendure repository](https://github.com/vendure-ecommerce/vendure) as the upstream remote to your clone:
|
|
|
+By default, if you do not specify the `DB` environment variable, it will use **MySQL/MariaDB**.
|
|
|
+
|
|
|
+If you want to develop against **PostgreSQL**:
|
|
|
+
|
|
|
+1. Run the `postgres_16` Docker container.
|
|
|
|
|
|
```bash
|
|
|
-git remote add upstream https://github.com/vendure-ecommerce/vendure.git
|
|
|
+docker-compose up -d postgres_16
|
|
|
```
|
|
|
|
|
|
-This lets you pull updates from the original repository directly to your local clone.
|
|
|
+2. Create a .env file in `/packages/dev-server` and declare the `DB` variable inside it:
|
|
|
+
|
|
|
+ ```env
|
|
|
+ DB=postgres
|
|
|
+ ```
|
|
|
+3. Now run the npm populate script.
|
|
|
|
|
|
-### 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.
|
|
|
+> You can also set the environment variable directly in the CLI:
|
|
|
>
|
|
|
-> Here is [GitHub's official guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) on keeping your forks synced.
|
|
|
+> ```bash
|
|
|
+> DB=postgres npm run populate
|
|
|
+> ```
|
|
|
|
|
|
-There are **three main ways** to keep your fork synchronized:
|
|
|
+### 5. Run the dev server
|
|
|
|
|
|
-#### Option 1: Using GitHub's Web Interface
|
|
|
+```bash
|
|
|
+cd packages/dev-server
|
|
|
+npm run dev
|
|
|
+```
|
|
|
|
|
|
-Navigate to your fork's GitHub page and click the `Sync fork` button.
|
|
|
+This will start the development server, and you should see output in your terminal indicating that the **Vendure development server** has successfully started.
|
|
|
|
|
|
-#### Option 2: Using GitHub CLI
|
|
|
+The output lists the available endpoints for the Shop API, Admin API, GraphiQL interfaces, asset server, development mailbox, and the Admin UI, along with their respective URLs.
|
|
|
|
|
|
-GitHub offers a handy open-source CLI tool - [GitHub CLI](https://cli.github.com/) - which allows you to sync your branch directly in your terminal:
|
|
|
+You can now access these services in your browser for development and testing.
|
|
|
|
|
|
-```bash
|
|
|
-gh repo sync
|
|
|
+Default Admin UI credentials:
|
|
|
+
|
|
|
+Username: `superadmin`
|
|
|
+Password: `superadmin`
|
|
|
+
|
|
|
+## Development Workflow
|
|
|
+
|
|
|
+### Testing Admin UI changes locally
|
|
|
+
|
|
|
+If you are making changes to the Admin UI, you need to start the Admin UI independent from the dev-server:
|
|
|
+
|
|
|
+> [!NOTE]
|
|
|
+> You don't need this step when you just use the Admin UI just
|
|
|
+> to test backend changes since the `dev-server` package ships with a default admin-ui
|
|
|
+
|
|
|
+```
|
|
|
+cd packages/admin-ui
|
|
|
+npm run dev
|
|
|
```
|
|
|
|
|
|
-#### Option 3: Using Git Commands
|
|
|
+This will run a separate process of admin-ui on "http://localhost:4200", you can login with the default credentials:
|
|
|
|
|
|
-If you prefer using `git` commands, which can be more robust in some circumstances:
|
|
|
+Username: `superadmin`
|
|
|
+Password: `superadmin`
|
|
|
+
|
|
|
+This will auto restart when you make changes to the Admin UI.
|
|
|
+
|
|
|
+### Testing your changes locally
|
|
|
+
|
|
|
+This example shows how to test changes to the `payments-plugin` package locally.
|
|
|
+This same workflow can be used for other packages as well.
|
|
|
+
|
|
|
+### Terminal Setup
|
|
|
+
|
|
|
+**In 2 separate terminal windows:**
|
|
|
+
|
|
|
+**Terminal 1** - Watch changes to the package:
|
|
|
|
|
|
-**First, fetch the latest changes:**
|
|
|
```bash
|
|
|
-git fetch upstream
|
|
|
-git checkout master
|
|
|
+cd packages/payments-plugin
|
|
|
+npm run watch
|
|
|
```
|
|
|
|
|
|
-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.
|
|
|
+**Terminal 2** - Run the development server:
|
|
|
|
|
|
-**Then, update your local and forked remote repositories:**
|
|
|
```bash
|
|
|
-git merge upstream/master
|
|
|
-git push origin master
|
|
|
+cd packages/dev-server
|
|
|
+npm run dev
|
|
|
+```
|
|
|
+
|
|
|
+> [!NOTE]
|
|
|
+> After making changes, you need to stop and restart the development server to see your changes.
|
|
|
+
|
|
|
+> [!WARNING]
|
|
|
+> If you are developing changes for the `core` package, you also need to watch the `common` package:
|
|
|
+
|
|
|
+in the root of the project:
|
|
|
+
|
|
|
+```shell
|
|
|
+npm run watch:core-common
|
|
|
```
|
|
|
----
|
|
|
+
|
|
|
+#### Development Workflow Summary
|
|
|
+
|
|
|
+1. Start your package watcher (npm run watch)
|
|
|
+2. Start the dev-server (npm run dev)
|
|
|
+3. Make code changes
|
|
|
+4. Wait for compilation to complete
|
|
|
+5. Restart dev-server to see changes
|
|
|
+
|
|
|
+### Interactive debugging
|
|
|
+
|
|
|
+To debug the dev server with VS Code use the included [launch.json](/.vscode/launch.json) configuration.
|
|
|
|
|
|
### Create a new branch
|
|
|
|
|
|
-This is where you can start implementing your changes:
|
|
|
+Before making changes, create a new branch for your work:
|
|
|
|
|
|
```bash
|
|
|
git checkout -b your-new-branch
|
|
|
```
|
|
|
|
|
|
-### Developing
|
|
|
-
|
|
|
-Follow our [development guide](https://github.com/vendure-ecommerce/vendure#development) to make sure you have a properly set up development environment.
|
|
|
+### Developing and committing changes
|
|
|
|
|
|
After implementing your changes, stage the changes and commit them. Refer to the [Commit message format](#commit-message-format)
|
|
|
+
|
|
|
```
|
|
|
git add .
|
|
|
git commit -m "type(scope): Message in present tense"
|
|
|
@@ -227,9 +307,152 @@ Navigate to your forked repository on GitHub and create a pull request from ther
|
|
|
|
|
|
**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.
|
|
|
|
|
|
----
|
|
|
+## Contribution Guidelines
|
|
|
+
|
|
|
+### Branches
|
|
|
+
|
|
|
+There are 3 important branches to know about:
|
|
|
|
|
|
-## Contributing to the documentation
|
|
|
+* `master` - the default branch
|
|
|
+* `minor` - a branch for commits which introduce new features which would go in the next [SemVer minor](https://semver.org/) release.
|
|
|
+* `major` - a branch for commits which introduce breaking changes which would go in the next [SemVer major](https://semver.org/) 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](./docs/README.md) for more details on the valid docs tags.
|
|
|
+
|
|
|
+```TypeScript
|
|
|
+/**
|
|
|
+ * @description
|
|
|
+ * Sets the value of the new API thing.
|
|
|
+ *
|
|
|
+ * @since 1.2.0
|
|
|
+ */
|
|
|
+myNewApi: number;
|
|
|
+```
|
|
|
+
|
|
|
+### Commit message format
|
|
|
+
|
|
|
+This repo uses [Conventional Commits](https://www.conventionalcommits.org).
|
|
|
+
|
|
|
+```
|
|
|
+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](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-both-and-breaking-change-footer).
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+## Advanced Topics
|
|
|
+
|
|
|
+### Code Generation
|
|
|
+
|
|
|
+[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator) is used to automatically create TypeScript interfaces for all GraphQL server operations and Admin UI queries. These generated interfaces are used in both the Admin UI and the server.
|
|
|
+
|
|
|
+Running `npm run codegen` will generate the following files:
|
|
|
+
|
|
|
+- [`packages/common/src/generated-types.ts`](./packages/common/src/generated-types.ts): Types, Inputs & resolver args relating to the Admin API
|
|
|
+- [`packages/common/src/generated-shop-types.ts`](./packages/common/src/generated-shop-types.ts): Types, Inputs & resolver args relating to the Shop API
|
|
|
+- [`packages/admin-ui/src/lib/core/src/common/generated-types.ts`](./packages/admin-ui/src/lib/core/src/common/generated-types.ts): Types & operations relating to the admin-ui queries & mutations.
|
|
|
+- [`packages/admin-ui/src/lib/core/src/common/introspection-result.ts`](./packages/admin-ui/src/lib/core/src/common/introspection-result.ts): Used by the Apollo Client [`IntrospectionFragmentMatcher`](https://www.apollographql.com/docs/react/data/fragments/#fragments-on-unions-and-interfaces) to correctly handle fragments in the Admin UI.
|
|
|
+- Also generates types used in e2e tests in those packages which feature e2e tests (core, elasticsearch-plugin, asset-server-plugin etc).
|
|
|
+
|
|
|
+### Testing
|
|
|
+
|
|
|
+#### Server Unit Tests
|
|
|
+
|
|
|
+The core and several other packages have unit tests which can be run all together by running `npm run test` from the root directory, or individually by running it from the package directory.
|
|
|
+
|
|
|
+Unit tests are co-located with the files which they test, and have the suffix `.spec.ts`.
|
|
|
+
|
|
|
+If you're getting `Error: Bindings not found.`, please run `npm rebuild @swc/core`.
|
|
|
+
|
|
|
+#### End-to-end Tests
|
|
|
+
|
|
|
+Certain packages have e2e tests, which are located at `/packages/<n>/e2e/`. All e2e tests can be run by running `npm run e2e` from the root directory, or individually by running it from the package directory.
|
|
|
+
|
|
|
+e2e tests use the `@vendure/testing` package. For details of how the setup works, see the [Testing docs](https://docs.vendure.io/guides/developer-guide/testing/).
|
|
|
+
|
|
|
+When **debugging e2e tests**, set an environment variable `E2E_DEBUG=true` which will increase the global Jest timeout and allow you to step through the e2e tests without the tests automatically failing due to timeout.
|
|
|
+
|
|
|
+### Release Process
|
|
|
+
|
|
|
+All packages in this repo are released at every version change (using [Lerna's fixed mode](https://lerna.js.org/docs/features/version-and-publish#fixedlocked-mode-default)). This simplifies both the development (tracking multiple disparate versions is tough) and also the developer experience for users of the framework (it is simple to see that all packages are up-to-date and compatible).
|
|
|
+
|
|
|
+To make a release:
|
|
|
+
|
|
|
+#### 1. `npm run publish-release`
|
|
|
+
|
|
|
+It will run `lerna version` which will prompt for which version to update to. Although we are using [conventional commits](https://www.conventionalcommits.org), the version is not automatically being calculated from the commit messages. Therefore, the next version should be manually selected.
|
|
|
+
|
|
|
+Next it will build all packages to ensure the distributed files are up to date.
|
|
|
+
|
|
|
+Finally, the command will create changelog entries for this release and create a tagged commit.
|
|
|
+
|
|
|
+#### 2. `git push origin master --follow-tags`
|
|
|
+
|
|
|
+The reason we do not rely on Lerna to push the release to Git is that this repo has a lengthy pre-push hook which runs all tests and builds the Admin UI. This long wait then invalidates the npm OTP and the publish will fail. So the solution is to publish first and then push.
|
|
|
+
|
|
|
+#### 3. Create a GitHub release
|
|
|
+
|
|
|
+Finally, a GitHub release should be created based on the tag generated by Lerna. This will trigger the "Publish to npmjs" workflow
|
|
|
+which will publish & sign each package.
|
|
|
+
|
|
|
+## Specific Contributions
|
|
|
+
|
|
|
+### Contributing to the documentation
|
|
|
|
|
|
For our [documentation](https://docs.vendure.io/), we use [Docusaurus](https://docusaurus.io/).
|
|
|
|
|
|
@@ -253,11 +476,13 @@ docs/docs
|
|
|
> [!NOTE]
|
|
|
> Files in the [reference](https://docs.vendure.io/reference/) directory are auto-generated. To edit reference documentation, modify the [JSDoc](https://jsdoc.app/about-getting-started) comments in the source code and run `npm run docs:build` from the project root directory.
|
|
|
|
|
|
-## Contributing to the Admin UI translations
|
|
|
+### 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](https://github.com/vendure-ecommerce/vendure/blob/master/packages/admin-ui/README.md#localization) in the admin-ui package.
|
|
|
|
|
|
-## Where to get help
|
|
|
+## Help & Support
|
|
|
+
|
|
|
+### Where to get help
|
|
|
|
|
|
We have an active discord community, join us there and ask away!
|
|
|
[Vendure Discord](https://www.vendure.io/community)
|
|
|
@@ -265,17 +490,18 @@ We have an active discord community, join us there and ask away!
|
|
|
Read the documentation - Our comprehensive [documentation](https://docs.vendure.io/) 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
|
|
|
+
|
|
|
+### Contributor License Agreement
|
|
|
|
|
|
All contributors are required to agree to the [Contributor License Agreement](./license/CLA.md) 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
|
|
|
+### Issue Triage Guidelines
|
|
|
|
|
|
This section is meant for maintainers to help triage issues.
|
|
|
|
|
|
-### Quality Control
|
|
|
+#### Quality Control
|
|
|
|
|
|
- [ ] Does the issue have a **clear title and description**?
|
|
|
- [ ] Was the **issue template followed** and is all required info available?
|
|
|
@@ -285,15 +511,15 @@ 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
|
|
|
+#### 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
|
|
|
+#### 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
|
|
|
+#### Stale Issues
|
|
|
|
|
|
Issues that need more information should be closed after 1 month of inactivity.
|
Housein Abo Shaar