zitadel/CONTRIBUTING.md

Contributing to ZITADEL

Introduction

Thank you for your interest about how to contribute! As you might know there is more than code to contribute. You can find all information needed to start contributing here.

Please give us and our community the chance to get rid of security vulnerabilities by responsibly disclose this kind of issues by contacting security@zitadel.com.

The strongest part of a community is the possibility to share thoughts. That's why we try to react as soon as possible to your ideas, thoughts and feedback. We love to discuss as much as possible in an open space like in the issues and discussions section here or in our chat, but we understand your doubts and provide further contact options here.

If you want to give an answer or be part of discussions please be kind. Treat others like you want to be treated. Read more about our code of conduct here.

What can I contribute?

For people who are new to ZITADEL: We flag issues which are a good starting point to start contributing. You find them here

Make ZITADEL more popular and give it a ⭐

Help shaping the future of ZITADEL:

• Join our chat and discuss with us or others.
• Ask or answer questions in the issues section
• Share your thoughts and ideas in the discussions section

Contribute

• Contribute code
• If you found a mistake on our docs page or something is missing please read the docs section
• Translate and improve texts

Follow @zitadel on twitter

How to contribute

We strongly recommend to talk to us before you start contributing to streamline our and your work.

We accept contributions through pull requests. You need a github account for that. If you are unfamiliar with git have a look at Github's documentation on creating forks and creating pull requests. Please draft the pull request as soon as possible. Go through the following checklist before you submit the final pull request:

Submit a Pull Request (PR)

1. Fork the zitadel/zitadel repository on GitHub
2. On your fork, commit your changes to a new branch

git checkout -b my-fix-branch main

3. Make your changes following the guidelines in this guide. Make sure that all tests pass.

4. Commit the changes on the new branch

git commit --all

5. Merge the latest commit of the main-branch

6. Push the changes to your branch on Github

git push origin my-fix-branch

7. Use Semantic Release commit messages to simplify creation of release notes. In the title of the pull request correct tagging is required and will be requested by the reviewers.

8. On GitHub, send a pull request to zitadel:main. Request review from one of the maintainers.

Reviewing a Pull Request

The reviewers will provide you feedback and approve your changes as soon as they are satisfied. If we ask you for changes in the code, you can follow the GitHub Guide to incorporate feedback in your pull request.

Commit Messages

Make sure you use semantic release messages format.

<type>(<scope>): <short summary>

Type

Must be one of the following:

• feat: New Feature
• fix: Bug Fix
• docs: Documentation

Scope

This is optional to indicate which component is affected. In doubt, leave blank (<type>: <short summary>)

Short Summary

Provide a brief description of the change.

Contribute

The code consists of the following parts:

name	description	language	where to find
backend	Service that serves the grpc(-web) and RESTful API	go	API implementation
console	Frontend the user interacts with after he is logged in	Angular, Typescript	./console
login	Server side rendered frontend the user interacts with during login	go, go templates	./internal/api/ui/login
API definitions	Specifications of the API	Protobuf	./proto/zitadel
docs	Project documentation made with docusaurus	Docusaurus	./docs

Please validate and test the code before you contribute.

We add the label "good first issue" for problems we think are a good starting point to contribute to ZITADEL.

• Issues for first time contributors
• All issues

Backend / Login

To keep the code clean and understandable we use golangci-lint. We recommend to format the code with this linter while working on ZITADEL to simplify the review process. The configuration is located here.

To start the backend with a debugger run the main.go-file located in the root of ZITADEL and provide the arguments and env-variables from below. Ensure that the database is running by running docker compose -f ./build/local/docker-compose.yml up db. For additional information please use the documentation of your IDE.

Make sure to use the following configurations:

Console

By executing the commands of this section, you run everything you need to develop the console locally. The CockroachDB and the latest released ZITADEL binary are run in Docker containers on your local machine. You use the ZITADEL container as backend for your console. The console is run in your node environment using the angular development server, so you have fast feedback about your changes. Also, you learn how to run end-to-end tests and tear everything down, once you are happy with your changes.

The commands are tested against the following software versions:

• Docker version 20.10.17
• Node version v16.16.0
• npm version 8.11.0
• curl version 7.58.0

Run the database and the latests backend locally.

# Change to the console directory
cd ./console

# You just need the db and the zitadel services to develop the console against.
docker compose --file ../e2e/docker-compose.yaml up --detach db zitadel

When the backend is ready, you have the latest zitadel exposed at http://localhost:8080. You can now run a local development server with live code reloading at http://localhost:4200. To allow console access via http://localhost:4200, you have to configure the ZITADEL backend.

1. Navigate to http://localhost:8080/ui/console/projects.
2. When propted, login with zitadel-admin@zitadel.localhost and Password1!.
3. Select the ZITADEL project.
4. Select the Console application.
5. Select Redirect Settings
6. Add http://localhost:4200/auth/callback to the Redirect URIs
7. Add http://localhost:4200/signedout to the Post Logout URIs
8. Select the Save button

You can run the local console development server now.

# Console loads its target environment from the file console/src/assets/environment.json.
# Load it from the backend.
curl http://localhost:8080/ui/console/assets/environment.json > ./src/assets/environment.json

# Generate source files from Protos
npm run generate

# Install npm dependencies
npm install

# Start the server
npm start

Navigate to http://localhost:4200/. Make some changes to the source code and see how the browser is automatically updated. After making changes to the code, you should run the end-to-end-tests. Open another shell.

# Change to the e2e directory
cd ./e2e

# Install npm dependencies
npm install

# Run all tests in a headless browser
npm run e2e:dev

You can also open the test suite interactively for fast success feedback on specific tests.

# Run all tests in a headless browser
npm run open:dev

When you are happy with your changes, you can cleanup your environment

# Stop and remove the docker containers for zitadel and the database
docker compose down

API Definitions

Ensure the provided code meets the official style guide.

The following docker command builds the grpc stub into the correct folders:

docker build -f build/grpc/Dockerfile -t zitadel-base:local . \
    && docker build -f build/zitadel/Dockerfile . -t zitadel-go-base --target go-copy -o .

Testing

Contribute Docs

Project documentation is made with docusaurus and is located under ./docs. Please refer to the README for more information and local testing.

When making a pull request use docs(<scope>): <short summary> as title for the semantic release. Scope can be left empty (omit the brackets) or refer to the top navigation sections.

Contribute Internationalization

ZITADEL loads translations from four files:

• Console texts
• Login interface
• Email notification
• Common texts for success or error toasts

You may edit the texts in these files or create a new file for additional language support. Make sure you set the locale (ISO 639-1 code) as the name of the new language file.

Want to start ZITADEL?

You can find an installation guide for all the different environments here: https://docs.zitadel.com/docs/guides/installation

Did you find a security flaw?

• Please read Security Policy.