Skip to content

Commit 1126021

Browse files
behinddwallsbehinddwalls
committed
Remove Code Style duplication, merge SHELL.md into DEVELOPMENT.md
1 parent 0145c06 commit 1126021

5 files changed

Lines changed: 232 additions & 85 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 37 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,40 @@
11
# Contributing to SubmitQueue
22

3-
Thank you for your interest in contributing to SubmitQueue!
3+
Thank you for your interest in contributing to SubmitQueue! Whether you are reporting a bug, suggesting a feature, improving documentation, or writing code, your contribution is welcome.
44

55
## Getting Started
66

7-
See [doc/howto/DEVELOPMENT.md](doc/howto/DEVELOPMENT.md) for prerequisites, setup, and troubleshooting.
7+
1. Read the [Development Setup](doc/howto/DEVELOPMENT.md) guide for prerequisites, building, and running tests.
8+
2. Review the [Architecture Guide](CLAUDE.md) to understand project layout, conventions, and code style.
9+
3. Check the [Testing Guide](doc/howto/TESTING.md) for testing patterns and requirements.
810

911
## Development Workflow
1012

11-
1. Fork the repository and create a feature branch from `main`.
12-
2. Make your changes, following the project conventions.
13-
3. Add or update tests as appropriate.
14-
4. Run `make gazelle` if you added or removed Go files.
15-
5. Run `make test` to ensure unit tests pass.
16-
6. Commit with a clear, descriptive message.
17-
7. Open a pull request against `main`.
18-
19-
## Code Style
20-
21-
See [CLAUDE.md](CLAUDE.md) for code style conventions.
22-
23-
## Testing
24-
25-
See [doc/howto/TESTING.md](doc/howto/TESTING.md) for the full testing guide.
26-
27-
Key commands:
28-
29-
```bash
30-
make test # Unit tests
31-
make integration-test # Integration tests (Docker-based, auto-builds binaries)
32-
make e2e-test # End-to-end tests
33-
```
13+
1. Fork the repository and clone your fork.
14+
2. Create a feature branch from `main`:
15+
```bash
16+
git checkout -b yourname/short-description
17+
```
18+
Use branch naming like `yourname/short-description` or `fix/issue-123`.
19+
3. Make your changes, following the project conventions.
20+
4. Add or update tests as appropriate.
21+
5. Run `make gazelle` if you added or removed Go files.
22+
6. Run `make test` to ensure unit tests pass.
23+
7. Commit with a clear, descriptive message.
24+
8. Push to your fork:
25+
```bash
26+
git push origin yourname/short-description
27+
```
28+
9. Open a pull request against `main`.
3429

3530
## Pull Request Guidelines
3631

3732
- Keep PRs focused on a single change.
33+
- Reference related issues: use `Closes #123` for fixes or `Part of #123` for incremental work.
3834
- Include tests for new functionality.
39-
- Ensure all existing tests pass (`bazel test //...`).
40-
- Follow the existing code style and patterns (see [CLAUDE.md](CLAUDE.md) for detailed conventions).
35+
- Ensure all existing tests pass (`make test`).
36+
- Ensure CI passes before requesting review.
37+
- Follow the existing code style and patterns described in the [Architecture Guide](CLAUDE.md).
4138
- Fill out the PR template with a description, motivation, and test plan.
4239

4340
## Code Review
@@ -48,10 +45,22 @@ All submissions require review before merging. We use GitHub pull requests for t
4845

4946
Use [GitHub Issues](https://github.com/uber/submitqueue/issues) to report bugs or request features. Please use the provided [issue templates](.github/ISSUE_TEMPLATE/) and check existing issues before creating a new one.
5047

48+
## Communication
49+
50+
- **Bug reports and feature requests** — [GitHub Issues](https://github.com/uber/submitqueue/issues)
51+
- **Questions and discussions** — open an issue with the `question` label
52+
- **Security vulnerabilities** — see [SECURITY.md](SECURITY.md) (do not open public issues)
53+
5154
## Code of Conduct
5255

5356
This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
5457

58+
## Contributor License Agreement
59+
60+
Contributions to SubmitQueue require signing Uber's Contributor License Agreement (CLA). When you open your first pull request, a CLA bot will comment with instructions. The CLA must be signed before your PR can be reviewed or merged.
61+
62+
The CLA ensures that Uber has the necessary rights to distribute your contributions under the [Apache License 2.0](LICENSE). It does not change your rights to use your own contributions for any other purpose.
63+
5564
## License
5665

57-
By contributing to SubmitQueue, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).
66+
By contributing to SubmitQueue, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE). All contributions are also subject to the [Contributor License Agreement](#contributor-license-agreement).

‎README.md‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,17 @@
11
# SubmitQueue
22

3-
SubmitQueue is a speculative merge queue that keeps the main branch green at scale. In large monorepo environments, concurrent changes can introduce conflicts and broken builds. SubmitQueue solves this by serializing and validating changes before they land on main, ensuring that every commit point passes defined validations.
3+
[![CI](https://github.com/uber/submitqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/uber/submitqueue/actions/workflows/ci.yml)
4+
[![Go Version](https://img.shields.io/github/go-mod/go-version/uber/submitqueue)](go.mod)
5+
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
6+
7+
SubmitQueue is a high-performance speculative merge queue that keeps your trunk consistently green at scale. Rather than validating changes one at a time, SubmitQueue speculatively rebases and validates multiple changes in parallel against predicted future states of HEAD. When validations pass, changes land automatically. When they fail, SubmitQueue isolates the offending change and retries the rest — all without human intervention.
8+
9+
Designed for large monorepos and fast-moving teams where concurrent changes can introduce subtle conflicts and destabilize builds.
410

511
## Quick Start
612

13+
Requires Docker and Docker Compose. See [Development Setup](doc/howto/DEVELOPMENT.md) for full prerequisites.
14+
715
```bash
816
# Build everything
917
make build
@@ -23,10 +31,25 @@ make local-stop
2331

2432
See [example/README.md](example/README.md) for more examples including running individual services and clients.
2533

26-
## Developer Guide
34+
## Documentation
35+
36+
| Document | Description |
37+
|----------|-------------|
38+
| [Development Setup](doc/howto/DEVELOPMENT.md) | Prerequisites, build, environment, IDE setup |
39+
| [Contributing](CONTRIBUTING.md) | How to contribute, workflow, guidelines |
40+
| [Testing Guide](doc/howto/TESTING.md) | Unit, integration, and E2E testing patterns |
41+
| [Architecture Guide](CLAUDE.md) | Project layout, patterns, conventions |
42+
| [Examples](example/README.md) | Running services, clients, API reference |
43+
| [RFCs](doc/rfc/index.md) | Design documents and proposals |
2744

28-
See [CLAUDE.md](CLAUDE.md) for the full developer guide, including project layout, controller patterns, entity conventions, extension system, and development workflows.
45+
## Project Status
46+
47+
SubmitQueue is under active development. The core architecture is stable, but APIs may evolve before v1.0. We welcome contributions and feedback.
2948

3049
## Contributing
3150

32-
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started, development workflow, code style, and testing.
51+
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started.
52+
53+
## License
54+
55+
Licensed under the [Apache License 2.0](LICENSE).

‎SECURITY.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Security Policy
2+
3+
## Reporting a Vulnerability
4+
5+
If you discover a security vulnerability, **do not open a public GitHub issue.** Instead, please email **oss-security@uber.com** with a description of the vulnerability and steps to reproduce it.
6+
7+
We will acknowledge your report within **48 hours** and work with you to resolve the issue promptly.
8+
9+
## Supported Versions
10+
11+
Security patches are applied to the latest release on the `main` branch. We recommend always running the most recent version.

‎doc/howto/DEVELOPMENT.md‎

Lines changed: 157 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,36 @@
22

33
## Prerequisites
44

5-
- **Docker** and **Docker Compose** (for integration and e2e tests)
6-
- **direnv** (recommended — automatically loads `.envrc` so you can use `bazel` directly)
5+
- **Go 1.24+** — needed for `gopls`, `go mod`, and installing protoc plugins. Download from [go.dev/dl](https://go.dev/dl/). Note: Bazel manages its own Go toolchain for builds, but a local Go installation is required for editor tooling and dependency management.
6+
- **Docker** and **Docker Compose** — for integration and e2e tests, and for running services locally.
7+
- **direnv** (recommended) — automatically loads `.envrc` so you can use `bazel` directly instead of `./tool/bazel`.
78

8-
The project includes `./tool/bazel` (Bazelisk wrapper) and `.bazelversion`, so you don't need to install Bazel or Go separately.
9+
The project includes `./tool/bazel` (Bazelisk wrapper) and `.bazelversion`, so you don't need to install Bazel separately. Bazel manages its own Go toolchain for building and testing.
10+
11+
### Setting up direnv
12+
13+
```bash
14+
brew install direnv
15+
```
16+
17+
Add the hook for your shell:
18+
19+
```bash
20+
# zsh — add to ~/.zshrc
21+
eval "$(direnv hook zsh)"
22+
23+
# bash — add to ~/.bashrc
24+
eval "$(direnv hook bash)"
25+
26+
# fish — add to ~/.config/fish/config.fish
27+
direnv hook fish | source
28+
```
29+
30+
Then allow it in the project directory:
31+
32+
```bash
33+
direnv allow
34+
```
935

1036
## Clone and Build
1137

@@ -23,18 +49,98 @@ make build
2349
make test
2450
```
2551

52+
## Verify Your Setup
53+
54+
After cloning and building, run through this checklist to confirm everything works:
55+
56+
```bash
57+
# 1. Build all services
58+
make build
59+
60+
# 2. Run unit tests
61+
make test
62+
63+
# 3. Confirm Docker is running
64+
docker ps
65+
66+
# 4. Start the full stack
67+
make local-start
68+
69+
# 5. Verify services are up (Gateway on :8081, Orchestrator on :8082)
70+
make local-ps
71+
72+
# 6. Test Gateway with grpcurl
73+
grpcurl -plaintext -d '{"message": "hello"}' localhost:8081 uber.submitqueue.gateway.SubmitQueueGateway/Ping
74+
75+
# 7. Stop services
76+
make local-stop
77+
```
78+
79+
If any step fails, see [Troubleshooting](#troubleshooting) below.
80+
81+
## IDE Setup
82+
83+
### VS Code
84+
85+
Install the [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.Go), which uses `gopls` for code intelligence. It works with the project's `go.mod` out of the box.
86+
87+
### GoLand / IntelliJ
88+
89+
GoLand works with Go modules automatically. Open the project root and GoLand will detect `go.mod`.
90+
2691
## Optional Tools
2792

2893
```bash
2994
# macOS
30-
brew install protobuf grpcurl direnv
95+
brew install protobuf grpcurl
3196

3297
# Go protoc plugins (only if modifying .proto files)
3398
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
3499
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
35100
go install go.uber.org/yarpc/encoding/protobuf/protoc-gen-yarpc-go@latest
36101
```
37102

103+
## Common Make Targets
104+
105+
| Target | Description |
106+
|--------|-------------|
107+
| `make build` | Build all services |
108+
| `make test` | Run unit tests |
109+
| `make integration-test` | Run all integration tests (Docker-based) |
110+
| `make e2e-test` | Run end-to-end tests |
111+
| `make proto` | Regenerate protobuf files |
112+
| `make gazelle` | Update BUILD.bazel files |
113+
| `make local-start` | Start full stack (Gateway + Orchestrator + MySQL) |
114+
| `make local-ps` | Show running containers and ports |
115+
| `make local-logs` | View logs from all services |
116+
| `make local-stop` | Stop all services |
117+
| `make clean` | Clean generated files and binaries |
118+
| `make help` | Show all available targets with descriptions |
119+
120+
## Running Specific Tests
121+
122+
```bash
123+
# Run tests for a single package
124+
bazel test //gateway/controller:controller_test
125+
126+
# Run a single test function
127+
bazel test //gateway/controller:controller_test --test_filter=TestLand
128+
129+
# Run Gateway integration tests only
130+
make integration-test-gateway
131+
132+
# Run Orchestrator integration tests only
133+
make integration-test-orchestrator
134+
135+
# Run extension integration tests only
136+
make integration-test-extensions
137+
138+
# Run unit tests without cache
139+
make test-no-cache
140+
```
141+
142+
See [TESTING.md](TESTING.md) for the full testing guide, including integration and end-to-end test patterns.
143+
38144
## Troubleshooting
39145

40146
**Proto generation fails:**
@@ -52,10 +158,53 @@ go install go.uber.org/yarpc/encoding/protobuf/protoc-gen-yarpc-go@latest
52158
- Version is pinned in `.bazelversion`; use `./tool/bazel` or `bazel` with direnv
53159
- Try `bazel shutdown` and rebuild
54160

55-
## Testing
161+
**`gopls` or `go mod tidy` errors:**
162+
- Run `go mod download` to fetch all dependencies
163+
- Check that your Go version matches what's in `go.mod` (currently Go 1.24)
164+
- If using VS Code, restart the Go language server: `Ctrl+Shift+P` > "Go: Restart Language Server"
165+
166+
## Shell Auto-Completion
167+
168+
### zsh
56169

57-
See [TESTING.md](TESTING.md) for the full testing guide, including integration and end-to-end tests.
170+
Add to `~/.zshrc` for tab-completion of Makefile targets with descriptions:
171+
172+
```bash
173+
autoload -Uz compinit
174+
compinit
175+
176+
function _make_targets() {
177+
local -a targets
178+
local makefile_cache=".make_targets_cache"
179+
180+
if [[ -f Makefile ]]; then
181+
if [[ ! -f $makefile_cache ]] || [[ Makefile -nt $makefile_cache ]]; then
182+
awk -F':.*?## ' '/^[a-zA-Z0-9_-]+:.*?## / {printf "%s:%s\n", $1, $2}' Makefile > $makefile_cache
183+
fi
184+
targets=(${(f)"$(<$makefile_cache)"})
185+
if [[ -s $makefile_cache ]] && grep -q ':' $makefile_cache 2>/dev/null; then
186+
_describe 'make targets' targets
187+
else
188+
awk -F: '/^[a-zA-Z0-9_-]+:/ {print $1}' Makefile > $makefile_cache
189+
targets=(${(f)"$(<$makefile_cache)"})
190+
_describe 'make targets' targets
191+
fi
192+
fi
193+
}
194+
195+
compdef _make_targets make
196+
```
197+
198+
The completion cache (`.make_targets_cache`) is gitignored and automatically regenerates when the Makefile changes.
199+
200+
### bash
201+
202+
If you use `bash-completion`, Makefile target completion typically works out of the box. Otherwise, add to `~/.bashrc`:
203+
204+
```bash
205+
complete -W "\$(grep -oE '^[a-zA-Z0-9_-]+:' Makefile | sed 's/://')" make
206+
```
58207

59-
## Shell Configuration (Optional)
208+
### Universal alternative
60209

61-
See [SHELL.md](SHELL.md) for direnv setup and Make target auto-completion.
210+
Run `make help` to see all available targets and their descriptions at any time.

‎doc/howto/SHELL.md‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

0 commit comments

Comments
 (0)