Merge remote-tracking branch 'upstream/master'

Author: zawadzkidiana

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Cadence Samples
+
+This doc is intended for contributors to Cadence samples. 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 cadence-samples 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/uber-common/cadence-samples/labels/good%20first%20issue).
+
+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.
+
+### Documentation
+
+- Every sample must have a README.md
+- Include:
+  - What the sample demonstrates
+  - Real-world use cases
+  - How to run the sample
+  - Expected output
+  - Key concepts
+
+### Getting Help
+
+If you need help or have questions:
+
+- Join [CNCF Slack #cadence-users](https://communityinviter.com/apps/cloud-native/cncf)
+- Ask on [StackOverflow](https://stackoverflow.com/questions/tagged/cadence-workflow) with tag `cadence-workflow`
+- Open a [GitHub Discussion](https://github.com/uber-common/cadence-samples/discussions)
+- File an [issue](https://github.com/uber-common/cadence-samples/issues) for bugs
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We're all here to learn and help each other build better software.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
+
+---
+
+Thank you for contributing to Cadence samples! Your efforts help the entire community. 🚀
+

README.md

@@ -15,6 +15,7 @@ Learn more about Cadence at:
 - [Documentation](https://cadenceworkflow.io)
 - [Cadence Server](https://github.com/cadence-workflow/cadence)
 - [Cadence Go Client](https://github.com/cadence-workflow/cadence-go-client)
+- [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf) - Join **#cadence-users** channel on CNCF Slack
 
 ## 🚀 Quick Start
 

new_samples/client_samples/helloworld_tls/README.md

@@ -19,9 +19,14 @@ https://github.com/cadence-workflow/cadence/blob/e1267de12f8bc670fc84fab456d3495
    ```
 
 4. **Start cadence server with TLS**
-   ```bash
-   ./cadence-server --env development --zone tls start
-   ```
+To enable mTLS in Cadence server, you need to configure TLS settings and start the server with the appropriate environment configuration.
+Starting the Server with TLS
+Use the --zone flag to specify the TLS configuration when starting the Cadence server:
+
+./cadence-server --env development --zone tls start
+
+This will load [config/development.yaml](https://github.com/cadence-workflow/cadence/blob/e1267de12f8bc670fc84fab456d3495c8fc2f8a8/config/development.yaml) + [config/development_tls.yaml](https://github.com/cadence-workflow/cadence/blob/e1267de12f8bc670fc84fab456d3495c8fc2f8a8/config/development_tls.yaml). 
+See [CONTRIBUTING.md](https://github.com/cadence-workflow/cadence/blob/e1267de12f8bc670fc84fab456d3495c8fc2f8a8/CONTRIBUTING.md#4-run) for more details. 
 
 ## Running the Sample
 

new_samples/client_samples/helloworld_tls/hello_world_tls.go

@@ -80,7 +80,10 @@ func withTLSDialOption() (grpc.DialOption, error) {
 		RootCAs:            caCertPool,
 		Certificates:       []tls.Certificate{clientCert},
 	}
+	// Create TLS credentials from the TLS configuration
 	creds := credentials.NewTLS(&tlsConfig)
+	// Create a gRPC dial option with TLS credentials for secure connection
 	grpc.DialerCredentials(creds)
+	// Return the gRPC dial option configured with TLS credentials
 	return grpc.DialerCredentials(creds), nil
 }

new_samples/hello_world/README.md

@@ -0,0 +1,102 @@
+<!-- THIS IS A GENERATED FILE -->
+<!-- PLEASE DO NOT EDIT -->
+
+# Hello World Sample
+
+## Prerequisites
+
+0. Install Cadence CLI. See instruction [here](https://cadenceworkflow.io/docs/cli/).
+1. Run the Cadence server:
+    1. Clone the [Cadence](https://github.com/cadence-workflow/cadence) repository if you haven't done already: `git clone https://github.com/cadence-workflow/cadence.git`
+    2. Run `docker compose -f docker/docker-compose.yml up` to start Cadence server
+    3. See more details at https://github.com/uber/cadence/blob/master/README.md
+2. Once everything is up and running in Docker, open [localhost:8088](localhost:8088) to view Cadence UI.
+3. Register the `cadence-samples` domain:
+
+```bash
+cadence --env development --domain cadence-samples domain register
+```
+
+Refresh the [domains page](http://localhost:8088/domains) from step 2 to verify `cadence-samples` is registered.
+
+## Steps to run sample
+
+Inside the folder this sample is defined, run the following command:
+
+```bash
+go run .
+```
+
+This will call the main function in main.go which starts the worker, which will be execute the sample workflow code
+
+### Start your workflow
+
+This workflow takes an input message and greet you as response. Try the following CLI
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  workflow start \
+  --workflow_type cadence_samples.HelloWorldWorkflow \
+  --tl cadence-samples-worker \
+  --et 60 \
+  --input '{"message":"Cadence"}'
+```
+
+Here are the details to this command:
+
+* `--domain` option describes under which domain to run this workflow
+* `--env development` calls the "local" cadence server
+* `--workflow_type` option describes which workflow to execute
+* `-tl` (or `--tasklist`) tells cadence-server which tasklist to schedule tasks with. This is the same tasklist the worker polls tasks from. See worker.go
+* `--et` (or `--execution_timeout`) tells cadence server how long to wait until timing out the workflow
+* `--input` is the input to your workflow
+
+To see more options run `cadence --help`
+
+### View your workflow
+
+#### Cadence UI (cadence-web)
+
+Click on `cadence-samples` domain in cadence-web to view your workflow.
+
+* In Summary tab, you will see the input and output to your workflow
+* Click on History tab to see individual steps.
+
+#### CLI
+
+List workflows using the following command:
+
+```bash
+ cadence --env development --domain cadence-samples --workflow list
+```
+
+You can view an individual workflow by using the following command:
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  --workflow describe \
+ --wid <workflow_id>
+```
+
+* `workflow` is the noun to run commands within workflow scope
+* `describe` is the verb to return the summary of the workflow
+* `--wid` (or `--workflow_id`) is the option to pass the workflow id. If there are multiple "run"s, it will return the latest one.
+* (optional) `--rid` (or `--run_id`) is the option to pass the run id to describe a specific run, instead of the latest.
+
+To view the entire history of the workflow, use the following command:
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  --workflow show \
+ --wid <workflow_id>
+```
+
+## References
+
+* The website: https://cadenceworkflow.io
+* Cadence's server: https://github.com/uber/cadence
+* Cadence's Go client: https://github.com/uber-go/cadence-client
+

new_samples/hello_world/generator/README.md

@@ -0,0 +1,23 @@
+<!-- THIS IS A GENERATED FILE -->
+<!-- PLEASE DO NOT EDIT -->
+
+# Sample Generator
+
+This folder is NOT part of the actual sample. It exists only for contributors who work on this sample. Please disregard it if you are trying to learn about Cadence.
+
+To create a better learning experience for Cadence users, each sample folder is designed to be self contained. Users can view every part of writing and running workflows, including:
+
+* Cadence client initialization
+* Worker with workflow and activity registrations
+* Workflow starter
+* and the workflow code itself
+
+Some samples may have more or fewer parts depending on what they need to demonstrate.
+
+In most cases, the workflow code (e.g. `workflow.go`) is the part that users care about. The rest is boilerplate needed to run that workflow. For each sample folder, the workflow code should be written by hand. The boilerplate can be generated. Keeping all parts inside one folder gives early learners more value because they can see everything together rather than jumping across directories.
+
+## Contributing
+
+* When creating a new sample, follow the steps mentioned in the README file in the main samples folder.
+* To update the sample workflow code, edit the workflow file directly.
+* To update the worker, client, or other boilerplate logic, edit the generator file. If your change applies to all samples, update the common generator file inside the `template` folder. Edit the generator file in this folder only when the change should affect this sample alone.

new_samples/hello_world/generator/README_specific.md

@@ -0,0 +1,64 @@
+### Start your workflow
+
+This workflow takes an input message and greet you as response. Try the following CLI
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  workflow start \
+  --workflow_type cadence_samples.HelloWorldWorkflow \
+  --tl cadence-samples-worker \
+  --et 60 \
+  --input '{"message":"Cadence"}'
+```
+
+Here are the details to this command:
+
+* `--domain` option describes under which domain to run this workflow
+* `--env development` calls the "local" cadence server
+* `--workflow_type` option describes which workflow to execute
+* `-tl` (or `--tasklist`) tells cadence-server which tasklist to schedule tasks with. This is the same tasklist the worker polls tasks from. See worker.go
+* `--et` (or `--execution_timeout`) tells cadence server how long to wait until timing out the workflow
+* `--input` is the input to your workflow
+
+To see more options run `cadence --help`
+
+### View your workflow
+
+#### Cadence UI (cadence-web)
+
+Click on `cadence-samples` domain in cadence-web to view your workflow.
+
+* In Summary tab, you will see the input and output to your workflow
+* Click on History tab to see individual steps.
+
+#### CLI
+
+List workflows using the following command:
+
+```bash
+ cadence --env development --domain cadence-samples --workflow list
+```
+
+You can view an individual workflow by using the following command:
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  --workflow describe \
+ --wid <workflow_id>
+```
+
+* `workflow` is the noun to run commands within workflow scope
+* `describe` is the verb to return the summary of the workflow
+* `--wid` (or `--workflow_id`) is the option to pass the workflow id. If there are multiple "run"s, it will return the latest one.
+* (optional) `--rid` (or `--run_id`) is the option to pass the run id to describe a specific run, instead of the latest.
+
+To view the entire history of the workflow, use the following command:
+
+```bash
+cadence --env development \
+  --domain cadence-samples \
+  --workflow show \
+ --wid <workflow_id>
+```

new_samples/hello_world/generator/generate.go

@@ -0,0 +1,16 @@
+package main
+
+import "github.com/uber-common/cadence-samples/new_samples/template"
+
+func main() {
+	// Define the data for HelloWorld
+	data := template.TemplateData{
+		SampleName: "Hello World",
+		Workflows:  []string{"HelloWorldWorkflow"},
+		Activities: []string{"HelloWorldActivity"},
+	}
+
+	template.GenerateAll(data)
+}
+
+// Implement custom generator below

new_samples/hello_world/main.go

@@ -0,0 +1,20 @@
+// THIS IS A GENERATED FILE
+// PLEASE DO NOT EDIT
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func main() {
+	StartWorker()
+
+	done := make(chan os.Signal, 1)
+	signal.Notify(done, syscall.SIGINT)
+	fmt.Println("Cadence worker started, press ctrl+c to terminate...")
+	<-done
+}