From 900d83dfbec7944e731a8528e525d6bf4a31e962 Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Fri, 19 May 2023 16:19:35 +0200 Subject: [PATCH] docs: improve usage and contributing --- CODE_OF_CONDUCT.md | 128 --------------------------------------------- CONTRIBUTING.md | 64 ++++++++++++++++------- README.md | 45 ++++++++-------- 3 files changed, 68 insertions(+), 169 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index ac3f1296528..00000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 709d4788cd7..baef2a8885e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 -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 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 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). -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. - -### Pull Requests - -- 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 +- The latest changes are always in `main`, so please make your pull request against that branch. +- pull requests should be raised for any change +- üull 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 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 -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: ```sh -git clone https://github.com/zitadel/zitadel-typescript.git -cd zitadel-typescript +git clone https://github.com/zitadel/typescript.git +cd typescript ``` 3. Install packages. Developing requires Node.js v16: @@ -61,6 +85,6 @@ pnpm generate pnpm dev ``` -The application will be available on `http://localhost:3000` +The application is now available at `http://localhost:3000` That's it! 🎉 diff --git a/README.md b/README.md index a7a3f34c9a1..da0a803d57e 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,30 @@ # 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 ⚠️** 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. -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/client`: core components for establishing web client connection, grpc stub - `@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/). -### Utilities - -This repo has some additional tools: +## Tooling - [TypeScript](https://www.typescriptlang.org/) for static type checking - [ESLint](https://eslint.org/) for code linting - [Prettier](https://prettier.io) for code formatting -### Useful commands +## Useful Commands - `pnpm generate` - Build proto stubs for server and client package - `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 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. 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 @@ -63,13 +72,7 @@ To publish packages to a private npm organization scope, **remove** the followin ### 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) - -### 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 +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) ### Run Login UI