@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
feature/fix-clippy-on-stable-channel
claude/smbcloud-github-app-k9641p development feature/apps feature/build-release feature/ci-docs feature/ci-ruby-gems feature/cicd feature/completion feature/dist-nuget feature/fix-ci-sdk-pypi-rubygem feature/fix-clippy-on-stable-channel feature/fix-deployment-script feature/github-email feature/gresiq-v1 feature/project-new-structure feature/rsync-deploy feature/ruby-runner feature/sdk-npm feature/sdk-workflows feature/smbcloud-cli-release-npm feature/smbcloud-deploy feature/wasm main release/v0.7.4
md 155 lines 4.87 KB
Rendered Raw
1 # Contributing to smbcloud-cli
2
3 Thank you for considering contributing to smbcloud-cli! This document covers everything you need to get up and running.
4
5 ## Code of Conduct
6
7 By participating in this project you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please be respectful and considerate of others.
8
9 ## Prerequisites
10
11 - [Rust](https://rustup.rs/) — toolchain version is pinned in `rust-toolchain.toml` (currently 1.93)
12 - [cargo-workspaces](https://github.com/pksunkara/cargo-workspaces) — for publishing (`cargo install cargo-workspaces`)
13 - A `.env` file in the repo root containing `CLI_CLIENT_SECRET=<value>` — required at compile time by `dotenv_codegen`
14
15 ## Getting Started
16
17 1. Fork the repository on GitHub
18 2. Clone your fork:
19 ```sh
20 git clone https://github.com/your-username/smbcloud-cli.git
21 cd smbcloud-cli
22 ```
23 3. Create the `.env` file (ask a maintainer for the value, or use a local stub for offline work):
24 ```sh
25 echo "CLI_CLIENT_SECRET=your_secret_here" > .env
26 ```
27 4. Verify everything compiles:
28 ```sh
29 cargo check --workspace
30 ```
31 5. Create a branch for your work:
32 ```sh
33 git checkout -b your-feature-or-fix
34 ```
35
36 ## Development Workflow
37
38 ### Build
39
40 ```sh
41 # Debug build
42 cargo build
43
44 # Release build
45 cargo build --release
46 ```
47
48 The compiled binary is at `target/release/smb`.
49
50 ### Test
51
52 ```sh
53 cargo test --all-features
54 ```
55
56 ### Lint
57
58 ```sh
59 cargo clippy --workspace --tests -- -D warnings
60 ```
61
62 Fix any warnings before opening a PR — CI treats warnings as errors.
63
64 ### Format
65
66 ```sh
67 # Apply formatting
68 cargo fmt --all
69
70 # Check only (what CI runs)
71 cargo fmt --all -- --check
72 ```
73
74 ## Project Structure
75
76 This is a Cargo workspace. Each crate has a focused responsibility:
77
78 | Crate | Purpose |
79 | ------------------------------------ | ------------------------------------------ |
80 | `crates/cli` | Main binary (`smb`) — commands, entrypoint |
81 | `crates/smbcloud-model` | Shared API data types (`serde` structs) |
82 | `crates/smbcloud-network` | Network config and environment resolution |
83 | `crates/smbcloud-networking` | Core HTTP client (`SmbClient`) |
84 | `crates/smbcloud-auth` | Auth SDK API calls |
85 | `crates/smbcloud-networking-project` | Project API calls |
86 | `crates/smbcloud-utils` | Shared utilities |
87
88 All workspace-level dependencies are declared **once** in the root `Cargo.toml` under `[workspace.dependencies]`. When adding a dependency to a crate, add it to the root table first, then inherit it with `{ workspace = true }` in the crate's own `Cargo.toml`.
89
90 ## Coding Guidelines
91
92 These rules are enforced in code review and by CI:
93
94 - Use `?` to propagate errors — never `.unwrap()` or `.expect()` in production code.
95 - Never silently discard errors with `let _ =` on fallible operations.
96 - Do not create `mod.rs` files — use `src/some_module.rs` instead of `src/some_module/mod.rs`.
97 - Use full words for variable names — no abbreviations.
98 - Comments explain _why_, not _what_. Do not write comments that summarize code.
99 - Prefer adding to existing files over creating many small new files.
100
101 The full guidelines are in [AGENTS.md](AGENTS.md).
102
103 ## Submitting a Pull Request
104
105 1. Ensure all of the following pass locally before pushing:
106 ```sh
107 cargo check --workspace
108 cargo test --all-features
109 cargo clippy --workspace --tests -- -D warnings
110 cargo fmt --all -- --check
111 ```
112 2. Push your branch and open a PR against `main`.
113 3. Fill out the pull request template — in particular the **Release Notes** section.
114 4. A maintainer will review your changes and may request modifications.
115 5. Once approved, your PR will be merged.
116
117 ### PR Title Convention
118
119 Use a clear, imperative title that describes the change:
120
121 - ✅ `Fix crash when project name contains spaces`
122 - ✅ `Add logout command`
123 - ❌ `feat: add logout` (no conventional-commit prefixes)
124 - ❌ `Fixed some stuff.` (no past tense, no trailing punctuation)
125
126 ## Reporting Bugs
127
128 Use the GitHub issue tracker and fill out the bug report template. Please include:
129
130 - A clear description of the problem
131 - Steps to reproduce
132 - Expected vs. actual behaviour
133 - Your OS and the output of `smb --version`
134
135 ## Requesting Features
136
137 Use the GitHub issue tracker and fill out the feature request template. Describe the use case clearly — what problem does the feature solve?
138
139 ## Releasing
140
141 Releases are handled by maintainers using [cargo-workspaces](https://github.com/pksunkara/cargo-workspaces):
142
143 ```sh
144 # Bump versions interactively
145 cargo workspaces version
146
147 # Publish all crates
148 cargo workspaces publish --publish-as-is
149 ```
150
151 GitHub Actions workflows handle the GitHub release and npm wrapper publish automatically on tag push.
152
153 ## Questions?
154
155 Open a GitHub issue or reach out to the maintainers. We're happy to help.