From 6cfc11885448f0fbef4c0213f2f689037f7b5ab8 Mon Sep 17 00:00:00 2001 From: "Chang, Hui-Tang" Date: Thu, 21 Sep 2023 22:56:19 +0800 Subject: [PATCH] docs(readme): update readme and contributing guidelines (#357) Because - lack of contributing guidelines This commit - update readme and contributing guidelines --- .github/CODE_OF_CONDUCT.md | 133 ------------------------------- .github/CONTRIBUTING.md | 74 +++++++++++++---- .github/PULL_REQUEST_TEMPLATE.md | 7 -- .github/SECURITY.md | 3 - README.md | 4 + 5 files changed, 62 insertions(+), 159 deletions(-) delete mode 100644 .github/CODE_OF_CONDUCT.md delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/SECURITY.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index 5f4a38df..00000000 --- a/.github/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,133 +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, caste, color, 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 -[contact@instill.tech](contact@instill.tech). - -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.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 50f90cb2..63e53730 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,32 +1,74 @@ # Contributing Guidelines -Hello! Thanks for your interest in contributing to the codebase. +We appreciate your contribution to this amazing project! Any form of engagement is welcome, including but not limiting to +- feature request +- documentation wording +- bug report +- roadmap suggestion +- ...and so on! -## How to contribute +Please refer to the [community contributing section](https://github.com/instill-ai/community#contributing) for more details. -We love contribution to VDP in any forms: +## Development and codebase contribution -- Please refer to the [guideline](https://www.instill.tech/docs/development/setup-local-development/?utm_source=github&utm_medium=banner&utm_campaign=vdp_readme) for local development. +Before delving into the details to come up with your first PR, please familiarise yourself with the project structure of [Instill Core](https://github.com/instill-ai/community#instill-core). -- Please open a topic in the repository [Discussions](https://github.com/instill-ai/vdp/discussions) for any feature requests. +### Prerequisites -- Please open issues for bug report in the repository +Please refer to [here](../README.md#prerequisites) to make sure your environment has been all set. - - [vdp](https://github.com/instill-ai/vdp) for general issues; +### Launch the local dev system - - [pipeline-backend](https://github.com/instill-ai/pipeline-backend), [connector-backend](https://github.com/instill-ai/connector-backend), [model-backend](https://github.com/instill-ai/model-backend), [console](https://github.com/instill-ai/console), etc., for specific issues. +Clone the repo and launch the `latest` version of the codebase for all dependencies: -- Please refer to the [VDP project board](https://github.com/orgs/instill-ai/projects/5) to track progress. +```bash +$ git clone https://github.com/instill-ai/vdp.git && cd vdp -> **Note** -> Code in the main branch tracks under-development progress towards the next release and may not work as expected. If you are looking for a stable alpha version, please use [latest release](https://github.com/instill-ai/vdp/releases). +# launch all latest service components +$ make latest PROFILE=all +``` +The env variable `PROFILE` is intended to specify which service component you want to develop on +- `all` + When you set `PROFILE=all`, the whole `Instill Base` and `Instill VDP` stack will be launched, meaning you want to test the system as a whole -## Submitting a pull request +- `{service}` -To make an efficient review process, we very much appreciate if the PR commits + When you set `PROFILE={service}`, in which `{service}` can be `controller-vdp`, `connector` or `pipeline`, it means you want to develop on that particular service. The `make` command will launch the corresponding stack **WITHOUT** that service component and **WITH** all its dependencies. Given that, you can later on spin up and down the `{service}` in your dev container. Please take the [pipeline-backend](https://github.com/instill-ai/pipeline-backend#local-dev) as an example. -- follow the [conventional commits guidelines](https://www.conventionalcommits.org/), -- follow the [7 rules of commit messages](https://chris.beams.io/posts/git-commit/), and -- are rearranged to squash trivial commits together (use [git rebase](http://gitready.com/advanced/2009/03/20/reorder-commits-with-rebase.html)). +### Tear down the local dev system + +Simply run: +```bash +$ make down +``` + +### Build the local images + +We use Docker multi-stage builds to build a `instill/vdp-compose:{latest,release}` image which will be based on to run dind (docker-in-docker) to build all the images of `Instill VDP` defined in the compose file [docker-compose.build.yml](../docker-compose.build.yml). + +You can build the images by simply running: + +```bash +$ make build-{latest,release} +``` + +### Sending PRs + +Please take these general guidelines into consideration when you are sending a PR: + +1. **Fork the Repository:** Begin by forking the repository to your GitHub account. +2. **Create a New Branch:** Create a new branch to house your work. Use a clear and descriptive name, like `/`. +3. **Make and Commit Changes:** Implement your changes and commit them. We encourage you to follow these best practices for commits to ensure an efficient review process: + - Adhere to the [conventional commits guidelines](https://www.conventionalcommits.org/) for meaningful commit messages. + - Follow the [7 rules of commit messages](https://chris.beams.io/posts/git-commit/) for well-structured and informative commits. + - Rearrange commits to squash trivial changes together, if possible. Utilize [git rebase](http://gitready.com/advanced/2009/03/20/reorder-commits-with-rebase.html) for this purpose. +4. **Push to Your Branch:** Push your branch to your GitHub repository: `git push origin feat/`. +5. **Open a Pull Request:** Initiate a pull request to our repository. Our team will review your changes and collaborate with you on any necessary refinements. + +When you are ready to send a PR, we recommend you to first open a `draft` one. This will trigger a bunch of `integration-test` [workflows](https://github.com/instill-ai/vdp/tree/main/.github/workflows) running a thorough test suite on multiple platforms. After the tests are done and passed, you can now mark the PR `open` to notify the codebase owners to review. We appreciate your endeavour to pass the integration test for your PR to make sure the sanity with respect to the entire scope of **Instill Core**. + +## Last words + +Your contributions make a difference. Let's build something amazing together! diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c4c64b34..00000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ -Because - -- (write the reason why we need to consider this PR in a list) - -This commit - -- (write the summary of all commits in this PR in a list) diff --git a/.github/SECURITY.md b/.github/SECURITY.md deleted file mode 100644 index 0e2d367d..00000000 --- a/.github/SECURITY.md +++ /dev/null @@ -1,3 +0,0 @@ -If you discover a security issue in this repository, please contact us through security@instill.tech. - -Thanks for helping make the codebase safe for everyone. diff --git a/README.md b/README.md index 8bc9204a..c4701ad1 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,10 @@ The gRPC protocols in [protobufs](https://github.com/instill-ai/protobufs) provi For the OpenAPI documentation, access http://localhost:3001 after `make all`, or simply run `make doc`. +## Contributing + +Please refer to the [Contributing Guidelines](./.github/CONTRIBUTING.md) for more details. + ## Community support Please refer to the [community](https://github.com/instill-ai/community) repository.