Skip to content

Commit

Permalink
Update README and CONTRIBUTING files (#6578)
Browse files Browse the repository at this point in the history
  • Loading branch information
@taylanisikdemir
taylanisikdemir authored Dec 27, 2024
1 parent 0ed1d99 commit 1c7acf4
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 61 deletions.
37 changes: 14 additions & 23 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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!
Expand Down
87 changes: 49 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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).
Expand All @@ -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)


Expand Down

0 comments on commit 1c7acf4

Please sign in to comment.