Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Contributor Quickstart Guide

## Repository Layout
- `temporal-sdk`: core SDK implementation.
- `temporal-testing`: utilities to help write workflow and activity tests.
- `temporal-test-server`: in-memory Temporal server for fast tests.
- `temporal-serviceclient`: gRPC client for communicating with the service.
- `temporal-shaded`: prepackaged version of the SDK with shaded dependencies.
- `temporal-spring-boot-autoconfigure`: Spring Boot auto configuration.
- `temporal-kotlin`: Kotlin DSL for the SDK.
- `temporal-opentracing`: OpenTracing interceptor integration.

## General Guidance
- Avoid changing public API signatures. Anything under an `internal` directory
is not part of the public API and may change freely.
- The SDK code is written for Java 8.

## Building and Testing
1. Format the code before committing:
```bash
./gradlew --offline spotlessApply
```
2. Run the tests. This can take a long time so you may prefer to run individual tests.
```bash
./gradlew test
```
To run only the core SDK tests or a single test:
```bash
./gradlew :temporal-sdk:test --offline --tests "io.temporal.workflow.*"
./gradlew :temporal-sdk:test --offline --tests "<package.ClassName>"
```
3. Build the project:
```bash
./gradlew clean build
```

## Tests
- All tests for this each package is located in `$PACKAGE_NAME/src/test/java/io/temporal`, where `$PACKAGE_NAME` is the name of the package
- Workflow API tests should rely on `SDKTestWorkflowRule` to create a worker and
register workflows, activities, and nexus services.

## Commit Messages and Pull Requests
- Follow the [Chris Beams](http://chris.beams.io/posts/git-commit/) style for
commit messages.
- Every pull request should answer:
- **What changed?**
- **Why?**
- **Breaking changes?**
- **Server PR** (if the change requires a coordinated server update)
- Comments should be complete sentences and end with a period.

## Review Checklist
- `./gradlew spotlessCheck` must pass.
- All tests from `./gradlew test` must succeed.
- Add new tests for any new feature or bug fix.
- Update documentation for user facing changes.

For more details see `CONTRIBUTING.md` in the repository root.
1 change: 1 addition & 0 deletions temporal-kotlin/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Unlike the rest of this repository, this directory is for the Kotlin SDK so most of the code here is written in Kotlin, not Java.
7 changes: 7 additions & 0 deletions temporal-sdk/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
This directory contains the core Temporal SDK code, which is used to build Temporal applications. The SDK provides a set of APIs and libraries that allow developers to create, manage, and execute workflows and activities in a distributed environment. The SDK is designed to be easy to use and provides a high-level abstraction over the underlying Temporal service.

The SDK is written in Java and is designed to be used with the Temporal service. It provides a set of APIs for defining workflows and activities, as well as for managing the execution of those workflows and activities.

# Testing

All tests are written using JUnit4.
1 change: 1 addition & 0 deletions temporal-sdk/src/main/java/io/temporal/internal/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
All files in this directory and subdirectory are intended to be internal to the SDK and should not be used by external users. They do not have the same backwards compatibility guarantees as our other APIS
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,7 @@ public void process(@Nonnull T task) {
.uncaughtException(Thread.currentThread(), handler.wrapFailure(task, e));
}
} finally {
MDC.remove(LoggerTag.NAMESPACE);
MDC.remove(LoggerTag.TASK_QUEUE);
MDC.clear();
}
});
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
package io.temporal.worker;

import static org.junit.Assert.assertNull;

import io.temporal.activity.ActivityInterface;
import io.temporal.activity.ActivityMethod;
import io.temporal.testing.internal.SDKTestOptions;
import io.temporal.testing.internal.SDKTestWorkflowRule;
import io.temporal.workflow.Workflow;
import io.temporal.workflow.shared.TestWorkflows;
import org.junit.Rule;
import org.junit.Test;
import org.slf4j.MDC;

public class MdcClearedBetweenTasksTest {
@Rule
public SDKTestWorkflowRule testWorkflowRule =
SDKTestWorkflowRule.newBuilder()
.setWorkflowTypes(TestWorkflowImpl.class)
.setActivityImplementations(new SetMdcActivityImpl(), new GetMdcActivityImpl())
.build();

@Test
public void testMdcClearedBetweenActivities() {
TestWorkflows.TestWorkflowReturnString workflow =
testWorkflowRule.newWorkflowStub(TestWorkflows.TestWorkflowReturnString.class);
String result = workflow.execute();
assertNull(result);
}

public static class TestWorkflowImpl implements TestWorkflows.TestWorkflowReturnString {
private final SetMdcActivity setMdcActivity =
Workflow.newActivityStub(
SetMdcActivity.class, SDKTestOptions.newActivityOptions20sScheduleToClose());
private final GetMdcActivity getMdcActivity =
Workflow.newActivityStub(
GetMdcActivity.class, SDKTestOptions.newActivityOptions20sScheduleToClose());

@Override
public String execute() {
setMdcActivity.execute();
return getMdcActivity.execute();
}
}

@ActivityInterface
public interface SetMdcActivity {
@ActivityMethod(name = "setMdc")
void execute();
}

public static class SetMdcActivityImpl implements SetMdcActivity {
@Override
public void execute() {
MDC.put("mdcTest", "value");
}
}

@ActivityInterface
public interface GetMdcActivity {
@ActivityMethod(name = "getMdc")
String execute();
}

public static class GetMdcActivityImpl implements GetMdcActivity {
@Override
public String execute() {
return MDC.get("mdcTest");
}
}
}
7 changes: 7 additions & 0 deletions temporal-sdk/src/test/java/io/temporal/workflow/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Summary

This directory and sub directory contain tests for workflow APIs.

# Testing

Tests should use the `SDKTestWorkflowRule` to create a worker, register workflows, activities and nexus services.
Loading