TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-12-14 16:12:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve usage and contributing

Browse Source
This commit is contained in:
Elio Bischof
2023-05-19 16:19:35 +02:00
parent 6440f6c10d
commit 900d83dfbe
3 changed files with 68 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
CODE_OF_CONDUCT.md
View File

@@ -1,128 +0,0 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
legal@zitadel.com.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

64
CONTRIBUTING.md
View File

@@ -1,38 +1,62 @@
# Contributing to zitadel-typescript # 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 ## 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. Thank you for your interest about how to contribute!
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](mailto:security@zitadel.com). :attention: If you notice a possible **security vulnerability**, please don't hesitate to disclose any concern by contacting [security@zitadel.com](mailto:security@zitadel.com).
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.
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 also appreciate all your other ideas, thoughts and feedback and will take care of them as soon as possible.
We love to discuss as much as possible in an open space like in the ZITADEL [issues](https://github.com/zitadel/zitadel/issues) and [discussions](https://github.com/zitadel/zitadel/discussions) section or in our [chat](https://zitadel.com/chat), but we understand your doubts and provide further contact options [here](https://zitadel.com/contact). 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).
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](CODE_OF_CONDUCT.md). ## Pull Requests
## How to contribute Please consider the following guidelines when creating a pull request.
Anyone can be a contributor. Either you found a typo, or you have an awesome feature request you could implement, we encourage you to create 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 - üull requests need approval of a ZITADEL core engineer @zitadel/engineers before merging
- 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) - 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)
- We encourage you to test your changes, and if you have the opportunity, please make those tests part of the Pull Request - If you add new functionality, please provide the corresponding documentation as well and make it part of the pull request
- If you add new functionality, please provide the corresponding documentation as well and make it part of the Pull Request
## Setting Up The ZITADEL API
If you want to have a one-liner to get you up and running,
or if you want to develop against a ZITADEL API with the latest features,
or even add changes to ZITADEL itself at the same time,
you should develop against your local ZITADEL process.
However, it might be easier to develop against your ZITADEL Cloud instance
if you don't have docker installed
or have limited resources on your local machine.
### Developing Against Your Local ZITADEL Instance
### Developing Against Your ZITADEL Cloud Instance
### Setting up local environment ### Setting up local environment
A quick guide on how to setup your ZITADEL app locally to work on it and test out any changes: This guide assumes you develop against a local ZITADEL instance using docker compose.
If you want to develop against
A quick guide on how to setup your ZITADEL typescript app locally to work on it and test out any changes:
1. Clone the repo: 1. Clone the repo:
```sh ```sh
git clone https://github.com/zitadel/zitadel-typescript.git git clone https://github.com/zitadel/typescript.git
cd zitadel-typescript cd typescript
``` ```
3. Install packages. Developing requires Node.js v16: 3. Install packages. Developing requires Node.js v16:
@@ -61,6 +85,6 @@ pnpm generate
pnpm dev pnpm dev
``` ```
The application will be available on `http://localhost:3000` The application is now available at `http://localhost:3000`
That's it! 🎉 That's it! 🎉

45
README.md
View File

@@ -1,20 +1,30 @@
# ZITADEL typescript with Turborepo and Changesets # ZITADEL typescript with Turborepo and Changesets
This is an monorepo containing all typescript/javascript packages and applications for ZITADEL. Versioning and package publishing is handled by [Changesets](https://github.com/changesets/changesets) and fully automated with GitHub Actions. This repository contains all TypeScript and JavaScript packages and applications you need to create your own ZITADEL Login UI.
The repo makes use of the [build system Turbo](https://turbo.build/repo) and the [Changesets CLI for versioning the packages](https://github.com/changesets/changesets).
**⚠️ This repo and packages are in alpha state and subject to change ⚠️** **⚠️ This repo and packages are in alpha state and subject to change ⚠️**
The scope of functionality of this repo and packages is limited and under active development. The scope of functionality of this repo and packages is limited and under active development.
Once the package structure is set and all APIs are fully implemented we'll move this repo to beta state. Once the package structure is set and all APIs are fully implemented we'll move this repo to beta state.
You can read the [contribution guide](/CONTRIBUTING.md) on how to contribute. Questions can be raised in our [Discord Channel](https://discord.gg/erh5Brh7jE) or as an issue in this repo. You can read the [contribution guide](/CONTRIBUTING.md) on how to contribute.
Questions can be raised in our [Discord channel](https://discord.gg/erh5Brh7jE) or as a [GitHub issue](https://github.com/zitadel/typescript/issues).
## What's inside? ## Developing Your Own ZITADEL Login UI
This Turborepo includes the following: We think the easiest path of getting up and running, is the following:
### Apps and Packages 1. Fork and clone this repository
1. [Run the ZITADEL Cloud login UI locally](#run-login-ui)
1. Make changes to the code and see the effects live on your local machine
1. Study the rest of this README.md and get familiar and comfortable with how everything works.
1. Decide on a way of how you want to build and run your login UI.
You can reuse ZITADEL Clouds way.
But if you need more freedom, you can also import the packages you need into your self built application.
- `login`: The new login UI powered by Next.js ## Included Apps And Packages
- `login`: The login UI used by ZITADEL Cloud, powered by Next.js
- `@zitadel/server`: core components for establishing node client connection, grpc stub - `@zitadel/server`: core components for establishing node client connection, grpc stub
- `@zitadel/client`: core components for establishing web client connection, grpc stub - `@zitadel/client`: core components for establishing web client connection, grpc stub
- `@zitadel/react`: shared React utilities and components built with tailwindcss - `@zitadel/react`: shared React utilities and components built with tailwindcss
@@ -24,15 +34,13 @@ This Turborepo includes the following:
Each package and app is 100% [TypeScript](https://www.typescriptlang.org/). Each package and app is 100% [TypeScript](https://www.typescriptlang.org/).
### Utilities ## Tooling
This repo has some additional tools:
- [TypeScript](https://www.typescriptlang.org/) for static type checking - [TypeScript](https://www.typescriptlang.org/) for static type checking
- [ESLint](https://eslint.org/) for code linting - [ESLint](https://eslint.org/) for code linting
- [Prettier](https://prettier.io) for code formatting - [Prettier](https://prettier.io) for code formatting
### Useful commands ## Useful Commands
- `pnpm generate` - Build proto stubs for server and client package - `pnpm generate` - Build proto stubs for server and client package
- `pnpm build` - Build all packages and the login app - `pnpm build` - Build all packages and the login app
@@ -41,17 +49,18 @@ This repo has some additional tools:
- `pnpm changeset` - Generate a changeset - `pnpm changeset` - Generate a changeset
- `pnpm clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script) - `pnpm clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script)
## Versioning and Publishing packages ## Versioning And Publishing Packages
Package publishing has been configured using [Changesets](https://github.com/changesets/changesets). Here is their [documentation](https://github.com/changesets/changesets#documentation) for more information about the workflow. Package publishing has been configured using [Changesets](https://github.com/changesets/changesets).
Here is their [documentation](https://github.com/changesets/changesets#documentation) for more information about the workflow.
The [GitHub Action](https://github.com/changesets/action) needs an `NPM_TOKEN` and `GITHUB_TOKEN` in the repository settings. The [Changesets bot](https://github.com/apps/changeset-bot) should also be installed on the GitHub repository. The [GitHub Action](https://github.com/changesets/action) needs an `NPM_TOKEN` and `GITHUB_TOKEN` in the repository settings. The [Changesets bot](https://github.com/apps/changeset-bot) should also be installed on the GitHub repository.
Read the [changesets documentation](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md) for more information about this automation Read the [changesets documentation](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md) for more information about this automation
### npm ### NPM
If you want to publish package to the public npm registry and make them publicly available, this is already setup. If you want to publish a package to the public npm registry and make them publicly available, this is already setup.
To publish packages to a private npm organization scope, **remove** the following from each of the `package.json`'s To publish packages to a private npm organization scope, **remove** the following from each of the `package.json`'s
@@ -63,13 +72,7 @@ To publish packages to a private npm organization scope, **remove** the followin
### GitHub Package Registry ### GitHub Package Registry
See [Working with the npm registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#publishing-a-package-using-publishconfig-in-the-packagejson-file) See [working with the npm registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#publishing-a-package-using-publishconfig-in-the-packagejson-file)
### TODOs
- Buf setup to get grpc stub in the core package
- Decide whether a seperate client package is required to expose public client convenience methods only or generate a grpc-web output there
- Fix #/\* path in login application
### Run Login UI ### Run Login UI