mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-22 07:24:26 +00:00
Elio BischofandGitHub
b10455b51f
# Which Problems Are Solved - The previous monorepo in monorepo structure for the login app and its related packages was fragmented, complicated and buggy. - The process for building and testing the login container was inconsistent between local development and CI. - Lack of clear documentation as well as easy and reliable ways for non-frontend developers to reproduce and fix failing PR checks locally. # How the Problems Are Solved - Consolidated the login app and its related npm packages by moving the main package to `apps/login/apps/login` and merging `apps/login/packages/integration` and `apps/login/packages/acceptance` into the main `apps/login` package. - Migrated from Docker Compose-based test setups to dev container-based setups, adding support for multiple dev container configurations: - `.devcontainer/base` - `.devcontainer/turbo-lint-unit` - `.devcontainer/turbo-lint-unit-debug` - `.devcontainer/login-integration` - `.devcontainer/login-integration-debug` - Added npm scripts to run the new dev container setups, enabling exact reproduction of GitHub PR checks locally, and updated the pipeline to use these containers. - Cleaned up Dockerfiles and docker-bake.hcl files to only build the production image for the login app. - Cleaned up compose files to focus on dev environments in dev containers. - Updated `CONTRIBUTING.md` with guidance on running and debugging PR checks locally using the new dev container approach. - Introduced separate Dockerfiles for the login app to distinguish between using published client packages and building clients from local protos. - Ensured the login container is always built in the pipeline for use in integration and acceptance tests. - Updated Makefile and GitHub Actions workflows to use `--frozen-lockfile` for installing pnpm packages, ensuring reproducible installs. - Disabled GitHub release creation by the changeset action. - Refactored the `/build` directory structure for clarity and maintainability. - Added a `clean` command to `docks/package.json`. - Experimentally added `knip` to the `zitadel-client` package for improved linting of dependencies and exports. # Additional Changes - Fixed Makefile commands for consistency and reliability. - Improved the structure and clarity of the `/build` directory to support seamless integration of the login build. - Enhanced documentation and developer experience for running and debugging CI checks locally. # Additional Context - See updated `CONTRIBUTING.md` for new local development and debugging instructions. - These changes are a prerequisite for further improvements to the CI pipeline and local development workflow. - Closes #10276
219 lines
7.4 KiB
Markdown
219 lines
7.4 KiB
Markdown
# Contributing
|
|
|
|
:attention: In this CONTRIBUTING.md you read about contributing to this very repository.
|
|
If you want to develop your own login UI, please refer [to the README.md](./README.md).
|
|
|
|
## Introduction
|
|
|
|
Thank you for your interest about how to contribute!
|
|
|
|
:attention: If you notice a possible **security vulnerability**, please don't hesitate to disclose any concern by contacting [[email protected]](mailto:[email protected]).
|
|
You don't have to be perfectly sure about the nature of the vulnerability.
|
|
We will give them a high priority and figure them out.
|
|
|
|
We also appreciate all your other ideas, thoughts and feedback and will take care of them as soon as possible.
|
|
We love to discuss in an open space using [GitHub issues](https://github.com/zitadel/typescript/issues),
|
|
[GitHub discussions in the core repo](https://github.com/zitadel/zitadel/discussions)
|
|
or in our [chat on Discord](https://zitadel.com/chat).
|
|
For private discussions,
|
|
you have [more contact options on our Website](https://zitadel.com/contact).
|
|
|
|
## Pull Requests
|
|
|
|
The repository zitadel/typescript is a read-only mirror of the git subtree at zitadel/zitadel/login.
|
|
To submit changes, please open a Pull Request [in the zitadel/zitadel repository](https://github.com/zitadel/zitadel/compare).
|
|
|
|
If you already made changes based on the zitadel/typescript repository, these changes are not lost.
|
|
Submitting them to the main repository is easy:
|
|
|
|
1. [Fork zitadel/zitadel](https://github.com/zitadel/zitadel/fork)
|
|
1. Clone your Zitadel fork git clone https://github.com/<your-owner>/zitadel.git
|
|
1. Change directory to your Zitadel forks root.
|
|
1. Pull your changes into the Zitadel fork by running make login_pull LOGIN_REMOTE_URL=https://github.com/<your-owner>/typescript.git LOGIN_REMOTE_BRANCH=<your-typescript-fork-branch>.
|
|
1. Push your changes and [open a pull request to zitadel/zitadel](https://github.com/zitadel/zitadel/compare)
|
|
|
|
Please consider the following guidelines when creating a pull request.
|
|
|
|
- The latest changes are always in `main`, so please make your pull request against that branch.
|
|
- pull requests should be raised for any change
|
|
- Pull requests need approval of a Zitadel core engineer @zitadel/engineers before merging
|
|
- We use ESLint/Prettier for linting/formatting, so please run `pnpm lint:fix` before committing to make resolving conflicts easier (VSCode users, check out [this ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [this Prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) to fix lint and formatting issues in development)
|
|
- If you add new functionality, please provide the corresponding documentation as well and make it part of the pull request
|
|
|
|
### Setting up local environment
|
|
|
|
```sh
|
|
# Install dependencies. Developing requires Node.js v20
|
|
pnpm install
|
|
|
|
# Generate gRPC stubs
|
|
pnpm generate
|
|
|
|
# Start a local development server for the login and manually configure apps/login/.env.local
|
|
pnpm dev
|
|
```
|
|
|
|
The application is now available at `http://localhost:3000`
|
|
|
|
Configure apps/login/.env.local to target the Zitadel instance of your choice.
|
|
The login app live-reloads on changes, so you can start developing right away.
|
|
|
|
### <a name="latest"></a>Developing Against A Local Latest Zitadel Release
|
|
|
|
The following command uses Docker to run a local Zitadel instance and the login application in live-reloading dev mode.
|
|
Additionally, it runs a Traefik reverse proxy that exposes the login with a self-signed certificate at https://127.0.0.1.sslip.io
|
|
127.0.0.1.sslip.io is a special domain that resolves to your localhost, so it's safe to allow your browser to proceed with loading the page.
|
|
|
|
```sh
|
|
# Install dependencies. Developing requires Node.js v20
|
|
pnpm install
|
|
|
|
# Generate gRPC stubs
|
|
pnpm generate
|
|
|
|
# Start a local development server and have apps/login/.env.test.local configured for you to target the local Zitadel instance.
|
|
pnpm dev:local
|
|
```
|
|
|
|
Log in at https://127.0.0.1.sslip.io/ui/v2/login/loginname and use the following credentials:
|
|
**Loginname**: *[email protected]*
|
|
**Password**: _Password1!_.
|
|
|
|
The login app live-reloads on changes, so you can start developing right away.
|
|
|
|
### <a name="local"></a>Developing Against A Locally Compiled Zitadel
|
|
|
|
To develop against a locally compiled version of Zitadel, you need to build the Zitadel docker image first.
|
|
Clone the [Zitadel repository](https://github.com/zitadel/zitadel.git) and run the following command from its root:
|
|
|
|
```sh
|
|
# This compiles a Zitadel binary if it does not exist at ./zitadel already and copies it into a Docker image.
|
|
# If you want to recompile the binary, run `make compile` first
|
|
make login_dev
|
|
```
|
|
|
|
Open another terminal session at zitadel/zitadel/login and run the following commands to start the dev server.
|
|
|
|
```bash
|
|
# Install dependencies. Developing requires Node.js v20
|
|
pnpm install
|
|
|
|
# Start a local development server and have apps/login/.env.test.local configured for you to target the local Zitadel instance.
|
|
NODE_ENV=test pnpm dev
|
|
```
|
|
|
|
Log in at https://127.0.0.1.sslip.io/ui/v2/login/loginname and use the following credentials:
|
|
**Loginname**: *[email protected]*
|
|
**Password**: _Password1!_.
|
|
|
|
The login app live-reloads on changes, so you can start developing right away.
|
|
|
|
### Quality Assurance
|
|
|
|
Use `make` commands to test the quality of your code against a production build without installing any dependencies besides Docker.
|
|
Using `make` commands, you can reproduce and debug the CI pipelines locally.
|
|
|
|
```sh
|
|
# Reproduce the whole CI pipeline in docker
|
|
make login_quality
|
|
# Show other options with make
|
|
make help
|
|
```
|
|
|
|
Use `pnpm` commands to run the tests in dev mode with live reloading and debugging capabilities.
|
|
|
|
#### Linting and formatting
|
|
|
|
Check the formatting and linting of the code in docker
|
|
|
|
```sh
|
|
make login_lint
|
|
```
|
|
|
|
Check the linting of the code using pnpm
|
|
|
|
```sh
|
|
pnpm lint
|
|
pnpm format
|
|
```
|
|
|
|
Fix the linting of your code
|
|
|
|
```sh
|
|
pnpm lint:fix
|
|
pnpm format:fix
|
|
```
|
|
|
|
#### Running Unit Tests
|
|
|
|
Run the tests in docker
|
|
|
|
```sh
|
|
make login_test_unit
|
|
```
|
|
|
|
Run unit tests with live-reloading
|
|
|
|
```sh
|
|
pnpm test:unit
|
|
```
|
|
|
|
#### Running Integration Tests
|
|
|
|
Run the test in docker
|
|
|
|
```sh
|
|
make login_test_integration
|
|
```
|
|
|
|
Alternatively, run a live-reloading development server with an interactive Cypress test suite.
|
|
First, set up your local test environment.
|
|
|
|
```sh
|
|
# Install dependencies. Developing requires Node.js v20
|
|
pnpm install
|
|
|
|
# Generate gRPC stubs
|
|
pnpm generate
|
|
|
|
# Start a local development server and use apps/login/.env.test to use the locally mocked Zitadel API.
|
|
pnpm test:integration:setup
|
|
```
|
|
|
|
Now, in another terminal session, open the interactive Cypress integration test suite.
|
|
|
|
```sh
|
|
pnpm test:integration open
|
|
```
|
|
|
|
Show more options with Cypress
|
|
|
|
```sh
|
|
pnpm test:integration help
|
|
```
|
|
|
|
#### Running Acceptance Tests
|
|
|
|
To run the tests in docker against the latest release of Zitadel, use the following command:
|
|
|
|
:warning: The acceptance tests are not reliable at the moment :construction:
|
|
|
|
```sh
|
|
make login_test_acceptance
|
|
```
|
|
|
|
Alternatively, run can use a live-reloading development server with an interactive Playwright test suite.
|
|
Set up your local environment by running the commands either for [developing against a local latest Zitadel release](latest) or for [developing against a locally compiled Zitadel](compiled).
|
|
|
|
Now, in another terminal session, open the interactive Playwright acceptance test suite.
|
|
|
|
```sh
|
|
pnpm test:acceptance open
|
|
```
|
|
|
|
Show more options with Playwright
|
|
|
|
```sh
|
|
pnpm test:acceptance help
|
|
```
|