From 975f275a0294a98d2a16cbe5865b3283a672a7c4 Mon Sep 17 00:00:00 2001 From: "vpatil16@ext.uber.com" Date: Mon, 20 Oct 2025 12:21:24 -0700 Subject: [PATCH 1/3] docs: Convert slack links to CNCF, add link to contributing guide --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 7ea5032..46829f2 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,29 @@ uv run python scripts/dev.py clean uv run python scripts/dev.py check ``` +## Community & Contributing + +### Get Involved + +We'd love your help in making Cadence great! Here's how you can get involved: + +- **Join the conversation**: Connect with the Cadence community on [CNCF Slack](https://slack.cncf.io/) in the `#cadence` channel +- **Contributing Guide**: Please see our [Contributing Guide](https://github.com/cadence-workflow/cadence/blob/master/CONTRIBUTING.md) for details on: + - How to contribute + - Development workflow + - Code review process + - Community guidelines + +### Resources + +- [Cadence Documentation](https://cadenceworkflow.io/docs/) +- [Main Cadence Repository](https://github.com/uber/cadence) +- [Cadence Samples](https://github.com/cadence-workflow/cadence-samples) + +### Reporting Issues + +If you find a bug or have a feature request, please [open an issue](https://github.com/cadence-workflow/cadence-python-client/issues/new) on GitHub. + ## License Apache 2.0 License, please see [LICENSE](LICENSE) for details. From 0e3ff037cebda4bcc286324d2f1f3d648160da26 Mon Sep 17 00:00:00 2001 From: "vpatil16@ext.uber.com" Date: Mon, 20 Oct 2025 16:08:18 -0700 Subject: [PATCH 2/3] adressing review comments --- CONTRIBUTING.md | 31 ++++++++++++ README.md | 132 ++++++------------------------------------------ 2 files changed, 47 insertions(+), 116 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..26cd35b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing to Cadence Python Client + +This doc is intended for contributors to the Cadence Python Client. Thanks for considering to contribute ❤️ + +> 📚 **New to contributing to Cadence?** Check out our [Contributing Guide](https://cadenceworkflow.io/community/how-to-contribute/getting-started) for an overview of the contribution process across all Cadence repositories. This document contains Python client specific setup and development instructions. + +Once you go through the 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-python-client/labels/good%20first%20issue). +These issues are a great way to start contributing to Cadence Python Client. + +Join our community on the CNCF Slack workspace at [cloud-native.slack.com](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to reach out and discuss issues with the team. + +## Submitting Pull Requests + +1. Fork the repository +2. Create a feature branch from `main` +3. Make your changes following the code quality guidelines above +4. Write or update tests as needed +5. Ensure all tests pass and there are no linting/type errors +6. Submit a pull request with a clear description of your changes + +## Getting Help + +- **GitHub Issues**: [Report bugs or request features](https://github.com/cadence-workflow/cadence-python-client/issues/new) +- **CNCF Slack**: Join the **#cadence-users** channel at [cloud-native.slack.com](https://communityinviter.com/apps/cloud-native/cncf) +- **Stack Overflow**: Tag questions with `cadence-workflow` + +## License + +By contributing to Cadence Python Client, you agree that your contributions will be licensed under the Apache 2.0 License. + diff --git a/README.md b/README.md index 46829f2..3eb1552 100644 --- a/README.md +++ b/README.md @@ -16,135 +16,35 @@ ```bash git clone https://github.com/cadence-workflow/cadence-python-client.git cd cadence-python-client +uv venv +uv pip install -e ".[dev]" ``` -## Development +For detailed setup instructions, development workflow, and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). -### Setup +## Contributing -1. **Install protobuf (required):** - ```bash - # macOS - brew install protobuf@29 +We'd love your help in making Cadence great! Please review our [contribution guide](CONTRIBUTING.md). - # Linux/Other - # Install protobuf 29.x via your package manager - ``` +If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion. -2. **Install uv (recommended):** - ```bash - # macOS - brew install uv +## Community - # Linux/Other - curl -LsSf https://astral.sh/uv/install.sh | sh - source $HOME/.local/bin/env # Add to your shell profile for persistence - ``` +- [GitHub Issues](https://github.com/cadence-workflow/cadence-python-client/issues) + - Best for reporting bugs and feature requests +- [Stack Overflow](https://stackoverflow.com/questions/tagged/cadence-workflow) + - Best for Q&A and general discussion +- [Slack](https://communityinviter.com/apps/cloud-native/cncf) - Join **#cadence-users** channel on CNCF Slack + - Best for contributing/development discussion -3. **Create virtual environment and install dependencies:** - ```bash - uv venv - uv pip install -e ".[dev]" - ``` +## Documentation - Or if you prefer traditional pip: - ```bash - python3.11 -m venv venv - source venv/bin/activate # Windows: venv\Scripts\activate - pip install -e ".[dev]" - ``` +Visit [cadenceworkflow.io](https://cadenceworkflow.io) to learn more about Cadence. -### Generate Protobuf and gRPC Files - -Run the generation script: -```bash -# Using uv (recommended) -uv sync --extra dev -uv run python scripts/generate_proto.py - -# Or using traditional Python -python scripts/generate_proto.py -``` - -This will: -- Download protoc 29.1 binary -- Install grpcio-tools if needed -- Generate Python protobuf files in `cadence/api/v1/` -- Generate gRPC service files in `cadence/api/v1/` -- Create proper package structure with both protobuf and gRPC imports - -### Test - -Verify the generated files work: -```bash -# Using uv (recommended) -uv run python cadence/sample/simple_usage_example.py -uv run python cadence/sample/grpc_usage_example.py - -# Or using traditional Python -python cadence/sample/simple_usage_example.py -python test_grpc_with_examples.py -``` - -### Development Script - -The project includes a development script that provides convenient commands for common tasks: - -```bash -# Generate protobuf files -uv run python scripts/dev.py protobuf - -# Run tests -uv run python scripts/dev.py test - -# Run tests with coverage -uv run python scripts/dev.py test-cov - -# Run linting -uv run python scripts/dev.py lint - -# Format code -uv run python scripts/dev.py format - -# Install in development mode -uv run python scripts/dev.py install - -# Install with dev dependencies -uv run python scripts/dev.py install-dev - -# Build package -uv run python scripts/dev.py build - -# Clean build artifacts -uv run python scripts/dev.py clean - -# Run all checks (lint + test) -uv run python scripts/dev.py check -``` - -## Community & Contributing - -### Get Involved - -We'd love your help in making Cadence great! Here's how you can get involved: - -- **Join the conversation**: Connect with the Cadence community on [CNCF Slack](https://slack.cncf.io/) in the `#cadence` channel -- **Contributing Guide**: Please see our [Contributing Guide](https://github.com/cadence-workflow/cadence/blob/master/CONTRIBUTING.md) for details on: - - How to contribute - - Development workflow - - Code review process - - Community guidelines - -### Resources - -- [Cadence Documentation](https://cadenceworkflow.io/docs/) +- [Documentation](https://cadenceworkflow.io/docs/) - [Main Cadence Repository](https://github.com/uber/cadence) - [Cadence Samples](https://github.com/cadence-workflow/cadence-samples) -### Reporting Issues - -If you find a bug or have a feature request, please [open an issue](https://github.com/cadence-workflow/cadence-python-client/issues/new) on GitHub. - ## License Apache 2.0 License, please see [LICENSE](LICENSE) for details. From b56204378337ff43e8ed51a844b9560b646a73fa Mon Sep 17 00:00:00 2001 From: "vpatil16@ext.uber.com" Date: Mon, 20 Oct 2025 16:13:28 -0700 Subject: [PATCH 3/3] adressing review comments --- README.md | 115 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 97 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 3eb1552..9db7ee6 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ [Cadence](https://github.com/uber/cadence) is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way. +If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion. + `cadence-python-client` is the Python framework for authoring workflows and activities. ## Disclaimer @@ -16,34 +18,111 @@ ```bash git clone https://github.com/cadence-workflow/cadence-python-client.git cd cadence-python-client -uv venv -uv pip install -e ".[dev]" ``` -For detailed setup instructions, development workflow, and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). +## Development -## Contributing +### Setup -We'd love your help in making Cadence great! Please review our [contribution guide](CONTRIBUTING.md). +1. **Install protobuf (required):** + ```bash + # macOS + brew install protobuf@29 -If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion. + # Linux/Other + # Install protobuf 29.x via your package manager + ``` + +2. **Install uv (recommended):** + ```bash + # macOS + brew install uv + + # Linux/Other + curl -LsSf https://astral.sh/uv/install.sh | sh + source $HOME/.local/bin/env # Add to your shell profile for persistence + ``` + +3. **Create virtual environment and install dependencies:** + ```bash + uv venv + uv pip install -e ".[dev]" + ``` + + Or if you prefer traditional pip: + ```bash + python3.11 -m venv venv + source venv/bin/activate # Windows: venv\Scripts\activate + pip install -e ".[dev]" + ``` -## Community +### Generate Protobuf and gRPC Files -- [GitHub Issues](https://github.com/cadence-workflow/cadence-python-client/issues) - - Best for reporting bugs and feature requests -- [Stack Overflow](https://stackoverflow.com/questions/tagged/cadence-workflow) - - Best for Q&A and general discussion -- [Slack](https://communityinviter.com/apps/cloud-native/cncf) - Join **#cadence-users** channel on CNCF Slack - - Best for contributing/development discussion +Run the generation script: +```bash +# Using uv (recommended) +uv sync --extra dev +uv run python scripts/generate_proto.py + +# Or using traditional Python +python scripts/generate_proto.py +``` + +This will: +- Download protoc 29.1 binary +- Install grpcio-tools if needed +- Generate Python protobuf files in `cadence/api/v1/` +- Generate gRPC service files in `cadence/api/v1/` +- Create proper package structure with both protobuf and gRPC imports -## Documentation +### Test -Visit [cadenceworkflow.io](https://cadenceworkflow.io) to learn more about Cadence. +Verify the generated files work: +```bash +# Using uv (recommended) +uv run python cadence/sample/simple_usage_example.py +uv run python cadence/sample/grpc_usage_example.py + +# Or using traditional Python +python cadence/sample/simple_usage_example.py +python test_grpc_with_examples.py +``` -- [Documentation](https://cadenceworkflow.io/docs/) -- [Main Cadence Repository](https://github.com/uber/cadence) -- [Cadence Samples](https://github.com/cadence-workflow/cadence-samples) +### Development Script + +The project includes a development script that provides convenient commands for common tasks: + +```bash +# Generate protobuf files +uv run python scripts/dev.py protobuf + +# Run tests +uv run python scripts/dev.py test + +# Run tests with coverage +uv run python scripts/dev.py test-cov + +# Run linting +uv run python scripts/dev.py lint + +# Format code +uv run python scripts/dev.py format + +# Install in development mode +uv run python scripts/dev.py install + +# Install with dev dependencies +uv run python scripts/dev.py install-dev + +# Build package +uv run python scripts/dev.py build + +# Clean build artifacts +uv run python scripts/dev.py clean + +# Run all checks (lint + test) +uv run python scripts/dev.py check +``` ## License