Skip to content

Commit bbc7b0c

Browse files
author
ukgorclawbot-stack
committed
Add contributing and security guides
1 parent 7ef9805 commit bbc7b0c

File tree

5 files changed

+199
-0
lines changed

5 files changed

+199
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Contributing
2+
3+
Thanks for contributing to Telegram Multi-Bot Stack.
4+
5+
## Before You Open a Pull Request
6+
7+
Please keep changes small and focused.
8+
9+
Recommended order:
10+
11+
1. Open an issue first if the change is large or changes architecture
12+
2. Create a small branch for one topic only
13+
3. Run the fastest local checks before submitting
14+
4. Explain what changed and why
15+
16+
## Good First Contributions
17+
18+
These are especially welcome:
19+
20+
- documentation improvements
21+
- install flow fixes
22+
- CI fixes
23+
- configuration generator improvements
24+
- launchd template fixes
25+
- health check improvements
26+
27+
## Local Checks
28+
29+
Run these before opening a PR:
30+
31+
```bash
32+
python3 -m py_compile \
33+
bootstrap_bot_stack.py \
34+
configure_stack.py \
35+
reverse_export_bot_stack.py \
36+
make_migration_ready_stack.py \
37+
bot.py \
38+
group_bot.py \
39+
xhs_adapter.py \
40+
memory_store.py \
41+
routing.py \
42+
runners.py \
43+
task_registry.py
44+
45+
bash -n install.sh
46+
bash -n configure.sh
47+
bash -n apply_stack.sh
48+
bash -n health_check.sh
49+
bash -n scripts/shared-memory-write.sh
50+
zsh -n bootstrap_bot_stack.sh
51+
zsh -n run_role_bot.sh
52+
zsh -n run_group_bot.sh
53+
```
54+
55+
If your change affects generation logic, also run:
56+
57+
```bash
58+
python3 configure_stack.py
59+
python3 bootstrap_bot_stack.py --config bot_stack.bootstrap.toml
60+
python3 reverse_export_bot_stack.py
61+
python3 make_migration_ready_stack.py
62+
```
63+
64+
## What Not to Commit
65+
66+
Do not commit:
67+
68+
- real Telegram bot tokens
69+
- `.bot_tokens.env`
70+
- local `.env` files with secrets
71+
- generated runtime logs
72+
- sqlite runtime files
73+
- personal machine-specific secret values
74+
75+
The repository already ignores most runtime files. Please double-check anyway.
76+
77+
## Pull Request Checklist
78+
79+
- The change is focused and reviewable
80+
- README or INSTALL docs were updated if behavior changed
81+
- No secrets were added
82+
- Fast local checks passed
83+
- The PR description explains the user-facing impact
84+
85+
## Style Guidance
86+
87+
- Prefer small diffs over large refactors
88+
- Keep behavior consistent with the current stack layout
89+
- Do not introduce unnecessary dependencies
90+
- Prefer explicit errors and simple scripts
91+
92+
## Security Reports
93+
94+
If you want to report a security issue, do not open a public issue first.
95+
96+
Please follow the process in [SECURITY.md](./SECURITY.md).

‎README.en.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ Language:
5757
- English: [README.en.md](./README.en.md)
5858
- Chinese install: [INSTALL.md](./INSTALL.md)
5959
- English install: [INSTALL.en.md](./INSTALL.en.md)
60+
- Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
61+
- Security: [SECURITY.md](./SECURITY.md)
6062

6163
## Quick Start
6264

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
- English: [README.en.md](./README.en.md)
1818
- 中文安装：[INSTALL.md](./INSTALL.md)
1919
- English install: [INSTALL.en.md](./INSTALL.en.md)
20+
- 贡献指南：[CONTRIBUTING.md](./CONTRIBUTING.md)
21+
- 安全说明：[SECURITY.md](./SECURITY.md)
2022

2123
适合这些场景：
2224
- 团队协作群里的任务拆分和汇报

‎RELEASE_NOTES_v0.1.4.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Telegram Multi-Bot Stack v0.1.4
2+
3+
This release makes the public repository more contributor-friendly and safer.
4+
5+
## What's New
6+
7+
- Added `CONTRIBUTING.md`
8+
- Added `SECURITY.md`
9+
- Linked both documents from the Chinese and English README files
10+
11+
## Why This Matters
12+
13+
- new contributors now have a clear PR and local-check workflow
14+
- security-sensitive reports now have a documented path
15+
- the repository is more complete as a public open-source project
16+
17+
## Quick Start
18+
19+
```bash
20+
git clone https://github.com/ukgorclawbot-stack/telegram-multi-bot-stack.git
21+
cd telegram-multi-bot-stack
22+
bash ./install.sh
23+
bash ./configure.sh
24+
bash ./apply_stack.sh
25+
```

‎SECURITY.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Security Policy
2+
3+
## Supported Scope
4+
5+
This project is a local multi-bot orchestration stack for Telegram on macOS.
6+
7+
Security-sensitive areas include:
8+
9+
- token handling
10+
- local env generation
11+
- launchd service generation
12+
- local file permissions
13+
- memory and runtime state storage
14+
15+
## Please Do Not Report Publicly First
16+
17+
If you discover a security issue, do not open a public issue with exploit details first.
18+
19+
Instead:
20+
21+
1. Prepare a short description
22+
2. Include reproduction steps if possible
23+
3. State whether secrets, tokens, or local file access are involved
24+
4. Report it privately to the maintainer
25+
26+
## What Counts as a Security Issue
27+
28+
Examples:
29+
30+
- token leakage
31+
- secrets written into generated files or logs
32+
- unsafe default permissions
33+
- arbitrary code execution through generated config
34+
- unsafe path handling that could overwrite unintended files
35+
- unintended cross-bot memory exposure
36+
37+
## What Usually Does Not Count
38+
39+
Examples:
40+
41+
- general install questions
42+
- feature requests
43+
- cosmetic documentation issues
44+
- requests for new integrations
45+
46+
Those should go through normal issues or pull requests.
47+
48+
## Safe Contribution Rules
49+
50+
When contributing:
51+
52+
- never commit real tokens
53+
- never paste `.env` secrets into issues or pull requests
54+
- never include private machine paths that expose sensitive local structure beyond what is necessary
55+
- prefer sanitized examples and placeholders
56+
57+
## Temporary Mitigation Guidance
58+
59+
If you think secrets may have been exposed:
60+
61+
1. rotate the affected Telegram bot tokens immediately
62+
2. remove local generated env files if needed
63+
3. check launchd-generated env files and logs
64+
4. review `.bot_tokens.env`
65+
5. re-run local setup with sanitized values
66+
67+
## Local Security Hygiene
68+
69+
Before publishing changes, double-check:
70+
71+
- `.bot_tokens.env` is not staged
72+
- no runtime sqlite files are staged
73+
- no generated logs are staged
74+
- docs use placeholder paths where appropriate

0 commit comments

Comments
 (0)