From 1c7acf4df4e23725dd708ce0c81edf78a101778a Mon Sep 17 00:00:00 2001 From: taylanisikdemir Date: Fri, 27 Dec 2024 12:51:30 -0800 Subject: [PATCH] Update README and CONTRIBUTING files (#6578) --- CONTRIBUTING.md | 37 ++++++++------------- README.md | 87 ++++++++++++++++++++++++++++--------------------- 2 files changed, 63 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fba34d212a2..b518983d729 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,17 @@ # Developing Cadence -This doc is intended for contributors to `cadence` server (hopefully that's you!) +This doc is intended for contributors to Cadence backend. Thanks for considering to contribute ❤️ + +Once you go through rest of this doc and get familiar with local development setup, take a look at the list of issues labeled with +[good first issue](https://github.com/cadence-workflow/cadence/labels/good%20first%20issue). +These issues are a great way to start contributing to Cadence. Later when you are more familiar with Cadence, look at issues with +[up-for-grabs](https://github.com/cadence-workflow/cadence/labels/up-for-grabs). + +Feel free to join our [slack workspace](http://t.uber.com/cadence-slack) to reach out and discuss issues with the team. -Join our Slack channel(invite link in the [home page](https://github.com/cadence-workflow/cadence#cadence)) #development if you need help. ->Note: All contributors need to fill out the [Uber Contributor License Agreement](http://t.uber.com/cla) before we can merge in any of your changes + +:warning: Note: +>All contributors need to fill out the [Uber Contributor License Agreement](http://t.uber.com/cla) before we can merge in any of your changes ## Development Environment Below are the instructions of how to set up a development Environment. @@ -164,17 +172,6 @@ $./bin/helloworld See [instructions](service/worker/README.md) for setting up replication(XDC). -## Issues to start with - -Take a look at the list of issues labeled with -[good first issue](https://github.com/cadence-workflow/cadence/labels/good%20first%20issue). -These issues are a great way to start contributing to Cadence. - -Later when you are more familiar with Cadence, look at issues with -[up-for-grabs](https://github.com/cadence-workflow/cadence/labels/up-for-grabs). - - - ## Repository layout A Cadence server cluster is composed of four different services: Frontend, Matching, History and Worker(system). Here's what's in each top-level directory in this repository: @@ -254,18 +251,12 @@ Examples: #### Code Format and Licence headers checking -The project has strict rule about Golang format. You have to run +The project has strict rule about Golang format, import ordering and license declarations. You have to run ```bash -make fmt +make pr ``` -to re-format your code. Otherwise the CI(buildkite) test will fail. - -Also, this project is Open Source Software, and requires a header at the beginning of -all new source files you are adding. To verify that all files contain the header execute: +which will take care of formatting for you. -```bash -make copyright -``` ### Code review We take code reviews very seriously at Cadence. Please don't be deterred if you feel like you've received some hefty feedback. That's completely normal and expected—and, if you're an external contributor, we very much appreciate your contribution! diff --git a/README.md b/README.md index 0208f167738..45828622605 100644 --- a/README.md +++ b/README.md @@ -2,50 +2,42 @@ [![Build Status](https://badge.buildkite.com/159887afd42000f11126f85237317d4090de97b26c287ebc40.svg?theme=github&branch=master)](https://buildkite.com/uberopensource/cadence-server) [![Coverage](https://codecov.io/gh/cadence-workflow/cadence/graph/badge.svg?token=7SD244ImNF)](https://codecov.io/gh/cadence-workflow/cadence) [![Slack Status](https://img.shields.io/badge/slack-join_chat-white.svg?logo=slack&style=social)](http://t.uber.com/cadence-slack) - [![Github release](https://img.shields.io/github/v/release/cadence-workflow/cadence.svg)](https://github.com/cadence-workflow/cadence/releases) [![License](https://img.shields.io/github/license/cadence-workflow/cadence.svg)](http://www.apache.org/licenses/LICENSE-2.0) -[![GitHub stars](https://img.shields.io/github/stars/cadence-workflow/cadence.svg?style=social&label=Star&maxAge=2592000)](https://github.com/cadence-workflow/cadence/stargazers/) -[![GitHub forks](https://img.shields.io/github/forks/cadence-workflow/cadence.svg?style=social&label=Fork&maxAge=2592000)](https://github.com/cadence-workflow/cadence/network/) +Cadence Workflow is an open-source platform since 2017 for building and running scalable, fault-tolerant, and long-running workflows. This repository contains the core orchestration engine and tools including CLI, schema managment, benchmark and canary. -This repo contains the source code of the Cadence server and other tooling including CLI, schema tools, bench and canary. +## Getting Started -You can implement your workflows with one of our client libraries. -The [Go](https://github.com/cadence-workflow/cadence-go-client) and [Java](https://github.com/cadence-workflow/cadence-java-client) libraries are officially maintained by the Cadence team, -while the [Python](https://github.com/firdaus/cadence-python) and [Ruby](https://github.com/coinbase/cadence-ruby) client libraries are developed by the community. +Cadence backend consists of multiple services, a database (Cassandra/MySQL/PostgreSQL) and optionally Kafka+Elasticsearch. +As a user, you need a worker which contains your workflow implementation. +Once you have Cadence backend and worker(s) running, you can trigger workflows by using SDKs or via CLI. -You can also use [iWF](https://github.com/indeedeng/iwf) as a DSL framework on top of Cadence. +1. Start cadence backend components locally -See Maxim's talk at [Data@Scale Conference](https://atscaleconference.com/videos/cadence-microservice-architecture-beyond-requestreply) for an architectural overview of Cadence. +``` +docker-compose -f docker/docker-compose.yml up +``` -Visit [cadenceworkflow.io](https://cadenceworkflow.io) to learn more about Cadence. Join us in [Cadence Documentation](https://github.com/cadence-workflow/Cadence-Docs) project. Feel free to raise an Issue or Pull Request there. +2. Run the Samples -### Community -* [Github Discussion](https://github.com/cadence-workflow/cadence/discussions) - * Best for Q&A, support/help, general discusion, and annoucement -* [StackOverflow](https://stackoverflow.com/questions/tagged/cadence-workflow) - * Best for Q&A and general discusion -* [Github Issues](https://github.com/cadence-workflow/cadence/issues) - * Best for reporting bugs and feature requests -* [Slack](http://t.uber.com/cadence-slack) - * Best for contributing/development discussion - -## Getting Started +Try out the sample recipes for [Go](https://github.com/cadence-workflow/cadence-samples) or [Java](https://github.com/cadence-workflow/cadence-java-samples). -### Start the cadence-server +3. Visit UI -To run Cadence services locally, we highly recommend that you use [Cadence service docker](docker/README.md) to run the service. -You can also follow the [instructions](./CONTRIBUTING.md) to build and run it. +Visit http://localhost:8080 to check workflow histories and detailed traces. -Please visit our [documentation](https://cadenceworkflow.io/docs/operation-guide/) site for production/cluster setup. -### Run the Samples +### Client Libraries +You can implement your workflows with one of our client libraries: +- [Official Cadence Go SDK](https://github.com/cadence-workflow/cadence-go-client) +- [Official Cadence Java SDK](https://github.com/cadence-workflow/cadence-java-client) +There are also unofficial [Python](https://github.com/firdaus/cadence-python) and [Ruby](https://github.com/coinbase/cadence-ruby) SDKs developed by the community. -Try out the sample recipes for [Go](https://github.com/cadence-workflow/cadence-samples) or [Java](https://github.com/cadence-workflow/cadence-java-samples) to get started. +You can also use [iWF](https://github.com/indeedeng/iwf) as a DSL framework on top of Cadence. -### Use [Cadence CLI](https://cadenceworkflow.io/docs/cli/) +### CLI Cadence CLI can be used to operate workflows, tasklist, domain and even the clusters. @@ -56,23 +48,17 @@ You can use the following ways to install Cadence CLI: * Build the CLI binary yourself, check out the repo and run `make cadence` to build all tools. See [CONTRIBUTING](CONTRIBUTING.md) for prerequisite of make command. * Build the CLI image yourself, see [instructions](docker/README.md#diy-building-an-image-for-any-tag-or-branch) -Cadence CLI is a powerful tool. The commands are organized by **tabs**. E.g. `workflow`->`batch`->`start`, or `admin`->`workflow`->`describe`. +Cadence CLI is a powerful tool. The commands are organized by tabs. E.g. `workflow`->`batch`->`start`, or `admin`->`workflow`->`describe`. Please read the [documentation](https://cadenceworkflow.io/docs/cli/#documentation) and always try out `--help` on any tab to learn & explore. -### Use Cadence Web +### UI Try out [Cadence Web UI](https://github.com/cadence-workflow/cadence-web) to view your workflows on Cadence. (This is already available at localhost:8088 if you run Cadence with docker compose) -## Contributing - -We'd love your help in making Cadence great. Please review our [contribution guide](CONTRIBUTING.md). - -If you'd like to propose a new feature, first join the [Slack channel](http://t.uber.com/cadence-slack) to start a discussion and check if there are existing design discussions. Also peruse our [design docs](docs/design/index.md) in case a feature has been designed but not yet implemented. Once you're sure the proposal is not covered elsewhere, please follow our [proposal instructions](PROPOSALS.md). - -## Other binaries in this repo +### Other binaries in this repo #### Bench/stress test workflow tools See [bench documentation](./bench/README.md). @@ -96,7 +82,32 @@ The easiest way to get the schema tool is via homebrew. All you need is to check out the older version of schemas from this repo. Run `git checkout v0.21.3` to get the v0.21.3 schemas in [the schema folder](/schema). -## Stargazers over time +## Contributing + +We'd love your help in making Cadence great. Please review our [contribution guide](CONTRIBUTING.md). + +If you'd like to propose a new feature, first join the [Slack channel](http://t.uber.com/cadence-slack) to start a discussion. + +Please visit our [documentation](https://cadenceworkflow.io/docs/operation-guide/) site for production/cluster setup. + + +### Learning Resources +See Maxim's talk at [Data@Scale Conference](https://atscaleconference.com/videos/cadence-microservice-architecture-beyond-requestreply) for an architectural overview of Cadence. + +Visit [cadenceworkflow.io](https://cadenceworkflow.io) to learn more about Cadence. Join us in [Cadence Documentation](https://github.com/cadence-workflow/Cadence-Docs) project. Feel free to raise an Issue or Pull Request there. + +### Community +* [Github Discussion](https://github.com/cadence-workflow/cadence/discussions) + * Best for Q&A, support/help, general discusion, and annoucement +* [Github Issues](https://github.com/cadence-workflow/cadence/issues) + * Best for reporting bugs and feature requests +* [StackOverflow](https://stackoverflow.com/questions/tagged/cadence-workflow) + * Best for Q&A and general discusion +* [Slack](http://t.uber.com/cadence-slack) + * Best for contributing/development discussion + + +## Stars over time [![Stargazers over time](https://starchart.cc/uber/cadence.svg?variant=adaptive)](https://starchart.cc/uber/cadence)