Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (123 loc) · 8.83 KB

CONTRIBUTING.md

File metadata and controls

178 lines (123 loc) · 8.83 KB
Raw

Contributing to Azure Cosmos DB Shell

We welcome contributions and suggestions! Whether it's a bug fix, new feature, documentation improvement, or just a question — we'd love to hear from you.

Contributor License Agreement (CLA)

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit the CLA site.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

Ways to Contribute

Ideas, Feature Requests, and Bugs

We are open to all ideas and we want to get rid of bugs! Use the Issues section to:

  • Report a bug
  • Suggest a new feature or enhancement
  • Ask a question or start a discussion

Look for issues labeled good first issue if you're looking for a place to start.

Documentation

Found a typo or strangely worded sentences? Submit a PR! Documentation lives in the docs/ folder and the root README.md.

Code

Contribute bug fixes, features, or design changes by following the development setup below.

Development Setup

Prerequisites

  • .NET SDK 10.0+ (verify with dotnet --list-sdks)
  • Git
  • A code editor (VS Code recommended — the repo includes a build task)

Getting Started

# Clone the repository
git clone https://github.com/Azure/CosmosDBShell.git
cd CosmosDBShell

# Restore dependencies
dotnet restore CosmosDBShell.sln

# Build the solution
dotnet build CosmosDBShell.sln

# Run the shell locally
dotnet run --project CosmosDBShell/CosmosDBShell.csproj

# Run tests
dotnet test CosmosDBShell.sln

# Run tests with code coverage (or use the VS Code `coverage` task)
./tools/coverage.ps1

In VS Code, you can also build with Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS) (uses the predefined build task).

Project Architecture

CosmosDBShell/
├── Azure.Data.Cosmos.Shell.ArgumentParser/  # CLI argument parsing
├── Azure.Data.Cosmos.Shell.Commands/        # Each shell command (ls, cd, query, etc.)
├── Azure.Data.Cosmos.Shell.Core/            # Interpreter, state machine, command runner
├── Azure.Data.Cosmos.Shell.Parser/          # Lexer and AST for shell syntax
├── Azure.Data.Cosmos.Shell.States/          # Shell state (connected, in database, etc.)
├── Azure.Data.Cosmos.Shell.Mcp/             # MCP (Model Context Protocol) server
├── Azure.Data.Cosmos.Shell.Lsp/             # LSP server for editor integration
├── Azure.Data.Cosmos.Shell.Lsp.Semantics/   # Semantic analysis for the LSP server
├── Azure.Data.Cosmos.Shell.Util/            # Shared utilities and helpers
├── Azure.Data.Cosmos.Shell.KeyBindings/     # Key binding definitions
├── lang/                                    # Localization files (Fluent .ftl)
└── Program.cs                               # Entry point and CLI option parsing

CosmosDBShell.Tests/                         # Unit and integration tests
docs/                                        # User-facing documentation

Key Conventions

  • Commands are classes in Azure.Data.Cosmos.Shell.Commands/ using [CosmosCommand], [CosmosExample], [CosmosOption], and [CosmosParameter] attributes.
  • Localization strings live in lang/en.ftl (Fluent format). Keep help text aligned with actual CLI behavior.
  • Tests live in CosmosDBShell.Tests/. Add or update tests when changing behavior.
  • Match the existing C# style. Prefer clear names over abbreviations.

Script Language Tests

When changing value semantics, extend ValueOriginCases in StatementExecutionTests.cs. The matrix evaluates each operand as a literal, a JSON property, a loop variable, and a function argument/return, checking both result type and value across all combinations. Each combination runs with both raw JSON fixtures and shell-constructed JSON so serialization changes cannot silently alter the input's numeric type. Include repeated object/array reconstruction and integral decimal values when changing JSON conversion.

Exercise syntax and control flow through ShellInterpreter.RunCommandAsync or script-file execution, which includes production parse/semantic validation. Check that invalid statements prevent execution and that returns, failures, and cancellation restore call scopes. For editor changes, check symbol identity, definition/reference locations, and hover ranges as well as diagnostics.

Run the offline regression suite without a database:

dotnet test CosmosDBShell.Tests/CosmosDBShell.Tests.csproj --filter "Category!=Emulator"

Updating Localized Text

Edit CosmosDBShell/lang/en.ftl, then build normally:

dotnet build CosmosDBShell/CosmosDBShell.csproj

Local shell builds automatically update l10n/CosmosDBShell.json. The exporter does not rewrite an unchanged catalog, including files with different line endings. Commit the source and updated catalog together. This runs during a build, not on each editor save; design-time builds do not update the catalog.

Command examples use DescriptionKey rather than literal Description text:

[CosmosExample("query \"SELECT * FROM c\"", DescriptionKey = "command-query-example-1")]

Define the key in en.ftl. Keep existing example keys stable when reordering examples; use a new unused key for a new example. Translate descriptions, not executable example text, command names, flags, or machine-readable identifiers. User-facing runtime errors and theme-preview labels also use MessageService. Localization audits check built-in example keys as well as literal message lookups.

Welcome-screen labels are defined by shell-welcome-* keys in en.ftl and referenced as {{shell-welcome-*}} placeholders in CosmosDBShell/cosmos_welcome.ans. Keep the artwork, executable examples, and URLs outside translated strings. Packaging runs tools/Localization/build-localized-resources.ps1 to generate locale-specific Fluent files from the OneLoc JSON catalogs. Missing translated keys use the English source until OneLoc delivers them; unexpected keys and invalid placeholders still fail validation. Do not commit generated Fluent files.

CI builds only verify the committed catalog and fail if it is missing or stale; they never repair it. This applies when CI, TF_BUILD, GITHUB_ACTIONS, or ContinuousIntegrationBuild is true. To check locally without updating it:

dotnet build CosmosDBShell/CosmosDBShell.csproj -p:ContinuousIntegrationBuild=true

The independent Localization Catalog GitHub Actions check verifies the catalog without building the shell or generating translations. The build-test-package check also verifies it before building the shell and is already required on main. Repository administrators should keep that check required, or require Localization Catalog as a dedicated gate, on protected target branches.

Running Against the Emulator

You can develop and test without an Azure subscription by using the Azure Cosmos DB Emulator:

dotnet run --project CosmosDBShell/CosmosDBShell.csproj -- --connect "https://localhost:8081"

Submitting a Pull Request

  1. Fork the repository and create a feature branch from main.
  2. Make your changes — keep them focused and minimal.
  3. Add or update tests for any behavior changes.
  4. Update documentation (README.md, docs/) if the change is user-visible.
  5. Ensure the build passes: dotnet build CosmosDBShell.sln
  6. Ensure tests pass: dotnet test CosmosDBShell.sln
  7. Open a pull request against main with a clear description of what and why.

CI Pipelines

Local builds use the default NuGet sources (nuget.org).

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.