Skip to content

Commit b88e60d

Browse files
wax911wax911
committed
docs(project): add README, CONTRIBUTING, and CODE_OF_CONDUCT
- Minimal README with command table, quick start, and development setup - CONTRIBUTING with issue/PR guidelines, branch/commit conventions - CODE_OF_CONDUCT (Contributor Covenant v1.4)
1 parent 195811e commit b88e60d

3 files changed

Lines changed: 250 additions & 1 deletion

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
- Using welcoming and inclusive language
18+
- Being respectful of differing viewpoints and experiences
19+
- Gracefully accepting constructive criticism
20+
- Focusing on what is best for the community
21+
- Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
- The use of sexualized language or imagery and unwelcome sexual attention or advances
26+
- Trolling, insulting/derogatory comments, and personal or political attacks
27+
- Public or private harassment
28+
- Publishing others' private information, such as a physical or electronic address, without explicit permission
29+
- Other conduct which could reasonably be considered inappropriate in a professional setting
30+
31+
## Our Responsibilities
32+
33+
Project maintainers are responsible for clarifying the standards of acceptable
34+
behavior and are expected to take appropriate and fair corrective action in
35+
response to any instances of unacceptable behavior.
36+
37+
Project maintainers have the right and responsibility to remove, edit, or reject
38+
comments, commits, code, wiki edits, issues, and other contributions that are
39+
not aligned to this Code of Conduct, or to ban temporarily or permanently any
40+
contributor for other behaviors that they deem inappropriate, threatening,
41+
offensive, or harmful.
42+
43+
## Scope
44+
45+
This Code of Conduct applies both within project spaces and in public spaces
46+
when an individual is representing the project or its community. Examples of
47+
representing a project or community include using an official project e-mail
48+
address, posting via an official social media account, or acting as an appointed
49+
representative at an online or offline event. Representation of a project may be
50+
further defined and clarified by project maintainers.
51+
52+
## Enforcement
53+
54+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
55+
reported by contacting the project team at anitrendapp@gmail.com. The project
56+
team will review and investigate all complaints, and will respond in a way that
57+
it deems appropriate to the circumstances. The project team is obligated to
58+
maintain confidentiality with regard to the reporter of an incident. Further
59+
details of specific enforcement policies may be posted separately.
60+
61+
Project maintainers who do not follow or enforce the Code of Conduct in good
62+
faith may face temporary or permanent repercussions as determined by other
63+
members of the project's leadership.
64+
65+
## Attribution
66+
67+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
68+
version 1.4, available at [http://contributor-covenant.org/version/1/4][version].
69+
70+
[homepage]: http://contributor-covenant.org
71+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Contributing
2+
3+
When contributing to this repository, please first discuss the change you wish to make via a GitHub issue, email, or Discord with the owners of this repository before making a change.
4+
5+
Please note we have a [Code of Conduct](CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.
6+
7+
## Issue Guidelines
8+
9+
- Search existing issues for duplicates before creating a new one.
10+
- Keep individual issues for each suggestion, bug, or feature.
11+
- Titles should use a scoped prefix for visibility, for example `[config] Harden profile merge order` or `[generate] Port idempotent stack generation`.
12+
- Use labels for taxonomy such as `feature`, `bug`, `refactor`, or `docs` rather than encoding taxonomy into the title itself.
13+
14+
## Pull Request Guidelines
15+
16+
- Make individual pull requests for each issue, and link the issue in the PR description.
17+
- PR titles follow the format `<type>(<scope>): <brief summary>` and stay aligned with the branch intent.
18+
- Do not stage files excluded by `.gitignore`.
19+
- Commits should reference relevant issues or other PRs.
20+
- Automated pull requests should follow the same branch naming conventions as contributor PRs.
21+
22+
## Quality Standards
23+
24+
Exhaustive unit tests are mandatory for all PRs, demonstrating the cases guarded against and extent of coverage.
25+
26+
### Branch Naming
27+
28+
```
29+
<type>/<issue-number>-<short-description>
30+
```
31+
32+
When no issue number exists yet, use `<type>/<short-description>` temporarily and link the branch to the issue as soon as it is created.
33+
34+
Supported types:
35+
36+
- `feat` -- A new feature
37+
- `fix` -- A bug fix
38+
- `chore` -- Routine tasks, dependencies, and maintenance
39+
- `docs` -- Documentation only changes
40+
- `refactor` -- Code change that neither fixes a bug nor adds a feature
41+
- `test` -- Adding missing or correcting existing tests
42+
- `build` -- Changes that affect the build system or dependencies
43+
- `ci` -- Changes to CI configuration or automation scripts
44+
- `revert` -- Reverting a previous commit
45+
46+
Examples:
47+
48+
- `feat/1208-implement-override-merging`
49+
- `fix/1177-template-drift-in-config-init`
50+
- `docs/1234-update-contributing-guidelines`
51+
- `ci/update-deno-version`
52+
53+
### Commit Messages
54+
55+
```
56+
<type>(<scope>): <brief summary>
57+
```
58+
59+
Scope should be a module area such as `config`, `generate`, `render`, `cli`, `docker`, `secrets`, or `project`.
60+
61+
Examples:
62+
63+
- `feat(config): add profile overlay discovery`
64+
- `fix(render): handle nested $VAR without braces`
65+
- `chore(project): pin Deno version in CI`
66+
- `docs(contributing): clarify PR title format`
67+
68+
### Pull Request Titles
69+
70+
Use the same format `<type>(<scope>): <brief summary>` and keep the title consistent with the branch intent.
71+
72+
### Before Submitting
73+
74+
- Run `deno task check` (fmt, lint, type-check) and fix any issues.
75+
- Run `deno task test` and confirm all tests pass (existing and new).
76+
- Run `deno task coverage` and verify coverage targets are met (minimum 80% line coverage for `src/`).
77+
- Verify that no secrets, credentials, or local paths were committed.
78+
79+
## Code of Conduct
80+
81+
See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our community standards and enforcement policies.
82+
83+
---
84+
85+
Thank you for your contribution!

‎README.md‎

Lines changed: 94 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,94 @@
1-
# stackctl
1+
# stackctl
2+
3+
[![CI](https://github.com/AniTrend/stackctl/actions/workflows/ci.yml/badge.svg)](https://github.com/AniTrend/stackctl/actions/workflows/ci.yml)
4+
5+
A Deno-powered CLI for managing local Docker Compose stacks across multi-service repositories, with config-driven profiles, overrides, secrets, and render pipelines.
6+
7+
Status: **Early development** -- all 15 feature issues are planned and tracked on the [issue tracker](https://github.com/AniTrend/stackctl/issues).
8+
9+
---
10+
11+
## Commands
12+
13+
| Command | Status | Description |
14+
|---|---|---|
15+
| `stackctl init` | Planned | Generate commented `.stackctl` config |
16+
| `stackctl generate` | Planned | Generate `stacks/*.yml` from per-service sources |
17+
| `stackctl render` | Planned | Resolve `${VAR}` placeholders in stack files |
18+
| `stackctl overrides` | Planned | Profile and explicit override merging |
19+
| `stackctl up` | Planned | Deploy stacks to Docker Swarm |
20+
| `stackctl down` | Planned | Tear down stacks |
21+
| `stackctl status` | Planned | Show service status |
22+
| `stackctl logs` | Planned | Follow container logs |
23+
| `stackctl sync` | Planned | Sync images and volumes |
24+
| `stackctl doctor` | Planned | Validate environment |
25+
| `stackctl reload` | Planned | Re-render and reconcile without teardown |
26+
| `stackctl secrets` | Planned | Encrypt/decrypt/deploy/clean/check with SOPS+age |
27+
| `stackctl env` | Planned | Scaffold `.env` files from examples |
28+
| `stackctl plan` | Planned | Dry-run summary of all operations |
29+
| `stackctl completions` | Planned | Generate shell completions (bash/zsh/fish) |
30+
31+
---
32+
33+
## Quick Start
34+
35+
```bash
36+
# Install (once released)
37+
deno install -f --allow-run --allow-env --allow-read --allow-write \
38+
-n stackctl jsr:@anitrend/stackctl
39+
40+
# Initialize a config
41+
stackctl init
42+
43+
# Generate stacks from service sources
44+
stackctl generate
45+
46+
# See what would happen
47+
stackctl plan
48+
```
49+
50+
---
51+
52+
## Development
53+
54+
### Prerequisites
55+
56+
- [Deno 2.x](https://deno.com) (2.8.0+)
57+
58+
### Setup
59+
60+
```bash
61+
git clone git@github.com:AniTrend/stackctl.git
62+
cd stackctl
63+
64+
# Run tests
65+
deno task test
66+
67+
# Run checks
68+
deno task check
69+
70+
# Build a binary
71+
deno task build
72+
```
73+
74+
See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, commit conventions, and PR guidelines.
75+
76+
---
77+
78+
## License
79+
80+
```
81+
Copyright 2026 AniTrend
82+
83+
Licensed under the Apache License, Version 2.0 (the "License");
84+
you may not use this file except in compliance with the License.
85+
You may obtain a copy of the License at
86+
87+
http://www.apache.org/licenses/LICENSE-2.0
88+
89+
Unless required by applicable law or agreed to in writing, software
90+
distributed under the License is distributed on an "AS IS" BASIS,
91+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
92+
See the License for the specific language governing permissions and
93+
limitations under the License.
94+
```

0 commit comments

Comments
 (0)