From 11de1a583cf21196e66aafc7027416eec02a2d79 Mon Sep 17 00:00:00 2001
From: Andrey Markelov <andreymarkelov@dropbox.com>
Date: Mon, 20 Jul 2026 14:01:11 -0700
Subject: [PATCH] Add Contribution instructions

---
 CONTRIBUTING.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  13 +++---
 2 files changed, 117 insertions(+), 8 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..729a1f8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,112 @@
+# Contributing to `dbxcli`
+
+Thanks for your interest in improving `dbxcli`.
+
+## Before you start
+
+For non-trivial contributions, complete the Dropbox Contributor License Agreement:
+
+https://opensource.dropbox.com/cla/
+
+If you're planning a larger feature or behavior change, consider opening an issue first.
+
+## Development
+
+Requirements:
+- Go 1.25+
+- Git
+
+Build:
+```
+go build .
+```
+
+Run:
+```
+go run . --help
+```
+
+## Repository layout
+- cmd/            Cobra commands
+- docs/           Generated documentation
+- docs/json-schema/v1/  Generated JSON schemas
+- packaging/      Release packaging
+- tools/          Documentation and schema generators
+
+## Design principles
+
+`dbxcli` is designed for humans, scripts, CI pipelines, and AI agents.
+
+When contributing, prefer changes that preserve:
+- backward compatibility where practical
+- stable automation interfaces
+- predictable JSON output and JSON help
+- composable command-line behavior
+- cross-platform support
+
+## Making changes
+
+Keep pull requests focused.
+
+When adding or modifying commands:
+- update help text
+- add or update tests
+- preserve JSON compatibility when possible
+- regenerate documentation
+- regenerate JSON schemas if applicable
+
+See:
+- docs/automation.md
+- docs/json-schema/v1/README.md
+
+## Validation
+
+Run before submitting:
+```
+go test ./...
+go vet ./...
+go build ./...
+```
+
+For concurrency-sensitive changes:
+```
+go test -race ./...
+```
+
+Recommended:
+```
+golangci-lint run
+govulncheck ./...
+```
+
+## Generated files
+
+If command structure, help, or JSON metadata changes:
+```
+go run ./tools/gen-docs
+go run ./tools/gen-json-schemas
+```
+
+Ensure the generated files are committed.
+
+## Pull requests
+
+Please include:
+- what changed
+- why
+- validation performed
+- related issue (if any)
+
+Small, focused pull requests are easier to review.
+
+## Reporting bugs
+
+Include:
+- `dbxcli` version
+- operating system
+- command executed
+- expected behavior
+- actual behavior
+- reproduction steps
+
+Remove access tokens and other sensitive information before posting logs.
diff --git a/README.md b/README.md
index b8c841f..e581989 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 [![CI](https://github.com/dropbox/dbxcli/actions/workflows/ci.yml/badge.svg)](https://github.com/dropbox/dbxcli/actions/workflows/ci.yml)
 [![Scorecard](https://github.com/dropbox/dbxcli/actions/workflows/scorecard.yml/badge.svg)](https://github.com/dropbox/dbxcli/actions/workflows/scorecard.yml)
 [![CodeQL](https://github.com/dropbox/dbxcli/actions/workflows/codeql.yml/badge.svg)](https://github.com/dropbox/dbxcli/actions/workflows/codeql.yml)
+[![Release](https://github.com/dropbox/dbxcli/actions/workflows/release.yml/badge.svg)](https://github.com/dropbox/dbxcli/actions/workflows/release.yml)
 
 `dbxcli` is a scriptable Dropbox CLI for files, shared links, teams, and
 automation workflows. It is built for humans in the terminal, scripts, CI jobs,
@@ -264,26 +265,22 @@ dbxcli --help --output=json
 dbxcli put --help --output=json
 ```
 
-## Deeper documentation
+## Documentation
 
 * [Automation and JSON output](https://github.com/dropbox/dbxcli/blob/master/docs/automation.md)
 * [Sharing workflows](https://github.com/dropbox/dbxcli/blob/master/docs/sharing.md)
 * [JSON schema v1](https://github.com/dropbox/dbxcli/blob/master/docs/json-schema/v1/README.md)
 * [Release history](https://github.com/dropbox/dbxcli/blob/master/CHANGELOG.md)
+* [Contributing](https://github.com/dropbox/dbxcli/blob/master/CONTRIBUTING.md)
 
 Generated Cobra command docs live under `docs/commands/`, and CI verifies they
 stay in sync with the CLI.
 
 ## Contributing
 
-* If you are submitting a non-trivial change, please fill out the
-  [Dropbox Contributor License Agreement](https://opensource.dropbox.com/cla/)
-  first.
-* Open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
-  with a clear description of the change.
-* Include tests or manual validation details when relevant.
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, pull request guidelines, and the Dropbox Contributor License Agreement.
 
 ## Useful resources
 
-* [Go SDK documentation](https://pkg.go.dev/github.com/dropbox/dropbox-sdk-go-unofficial)
+* [Dropbox Go SDK](https://pkg.go.dev/github.com/dropbox/dropbox-sdk-go-unofficial)
 * [Dropbox API documentation](https://www.dropbox.com/developers/documentation/http/documentation)