Skip to content

Commit 7e5230b

Browse files
codefromkarlcodefromkarl
committed
docs: optimize GEO/SEO and add community governance files
- Make English README the primary (README.md), Chinese as README_ZH.md - Add keyword-rich SEO paragraphs in both languages - Position ContextAtlas as "context infrastructure" not just MCP server - Add CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - Add CONTRIBUTING.md with bug/feature/PR guidelines - Add structured issue templates (bug report, feature request) - Add PR template with checklist - Add metadata recommendations for GitHub topics/description
1 parent b17cf46 commit 7e5230b

10 files changed

Lines changed: 1216 additions & 700 deletions

File tree

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
karl@codefrom.karl.
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series of
86+
actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or permanent
93+
ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of other classes of beings.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within the
113+
community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
Community Impact Guidelines were inspired by
122+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123+
124+
For answers to common questions about this code of conduct, see the FAQ at
125+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126+
[https://www.contributor-covenant.org/translations][translations].
127+
128+
[homepage]: https://www.contributor-covenant.org
129+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130+
[Mozilla CoC]: https://github.com/mozilla/diversity
131+
[FAQ]: https://www.contributor-covenant.org/faq
132+
[translations]: https://www.contributor-covenant.org/translations

‎.github/CONTRIBUTING.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Contributing to ContextAtlas
2+
3+
Thank you for your interest in contributing to ContextAtlas! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Table of Contents
6+
7+
- [Bug Reports](#bug-reports)
8+
- [Feature Requests](#feature-requests)
9+
- [Pull Requests](#pull-requests)
10+
- [Development Setup](#development-setup)
11+
- [Code Style](#code-style)
12+
- [Commit Messages](#commit-messages)
13+
- [Documentation](#documentation)
14+
15+
## Bug Reports
16+
17+
Bug reports help us improve ContextAtlas. Please include:
18+
19+
- **ContextAtlas version**: Run `contextatlas --version` or check `package.json`
20+
- **Node.js version**: Run `node --version`
21+
- **Operating System**: Linux, macOS, or Windows
22+
- **CLI or MCP mode**: Whether you're using the CLI or MCP server mode
23+
- **Steps to reproduce**: Clear, numbered steps to reproduce the bug
24+
- **Expected behavior**: What you expected to happen
25+
- **Actual behavior**: What actually happened (include error messages if applicable)
26+
- **Additional context**: Screenshots, logs, or any other relevant information
27+
28+
## Feature Requests
29+
30+
We welcome feature requests! Please provide:
31+
32+
- **Problem description**: What problem or use case does this feature address?
33+
- **Proposed solution**: How do you envision this feature working?
34+
- **Alternatives considered**: What alternative approaches did you consider?
35+
- **Use case context**: How would this feature benefit users?
36+
37+
## Pull Requests
38+
39+
### PR Process
40+
41+
1. **Fork the repository** and create your branch from `main`
42+
2. **Make your changes** following our code style guidelines
43+
3. **Test thoroughly** to ensure your changes work as expected
44+
4. **Update documentation** if your changes affect user-facing behavior
45+
5. **Submit a pull request** with a clear description of the changes
46+
47+
### PR Checklist
48+
49+
- [ ] Code builds successfully (`pnpm build`)
50+
- [ ] Changes are tested locally
51+
- [ ] Documentation is updated if needed
52+
- [ ] Commit messages follow conventional commit format
53+
- [ ] Changes are backward compatible (unless breaking)
54+
- [ ] Related issues are referenced
55+
56+
### Development Setup
57+
58+
1. **Clone the repository**:
59+
```bash
60+
git clone https://github.com/codefromkarl/ContextAtlas.git
61+
cd ContextAtlas
62+
```
63+
64+
2. **Install dependencies**:
65+
```bash
66+
pnpm install
67+
```
68+
69+
3. **Build the project**:
70+
```bash
71+
pnpm build
72+
```
73+
74+
4. **Run in development mode**:
75+
```bash
76+
pnpm dev
77+
```
78+
79+
5. **Run tests** (if available):
80+
```bash
81+
pnpm test
82+
```
83+
84+
## Code Style
85+
86+
We use [Biome](https://biomejs.dev/) for code formatting and linting. The project configuration is in `biome.json`.
87+
88+
- **Formatting**: Run `pnpm biome format` to format code
89+
- **Linting**: Run `pnpm biome check` to check code style
90+
- **Auto-fix**: Run `pnpm biome check --write` to auto-fix issues
91+
92+
### Code Style Guidelines
93+
94+
- Use TypeScript for type safety
95+
- Follow the existing code structure and patterns
96+
- Write clear, self-documenting code with comments when necessary
97+
- Keep functions focused and modular
98+
- Use meaningful variable and function names
99+
100+
## Commit Messages
101+
102+
We follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
103+
104+
- `feat:` New features
105+
- `fix:` Bug fixes
106+
- `docs:` Documentation changes
107+
- `style:` Code style changes (formatting, etc.)
108+
- `refactor:` Code refactoring
109+
- `test:` Test additions or changes
110+
- `chore:` Build process or auxiliary tool changes
111+
112+
Examples:
113+
- `feat: add support for multiple memory stores`
114+
- `fix: resolve race condition in cache invalidation`
115+
- `docs: update installation instructions`
116+
117+
## Documentation
118+
119+
For comprehensive documentation, please refer to the main [README.md](../README.md) and the [docs/](../docs/) directory.
120+
121+
When making changes that affect user-facing behavior:
122+
123+
1. Update the relevant documentation files
124+
2. Ensure examples are accurate and up-to-date
125+
3. Consider adding migration guides for breaking changes
126+
4. Update the changelog if applicable
127+
128+
## Questions?
129+
130+
Feel free to open a discussion on [GitHub Discussions](https://github.com/codefromkarl/ContextAtlas/discussions) for questions or ideas that don't fit into a bug report or feature request.
131+
132+
---
133+
134+
Thank you for contributing to ContextAtlas! Your contributions help make this project better for everyone.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
name: Bug Report
2+
description: Report a problem or bug in ContextAtlas
3+
title: "[Bug]: "
4+
labels:
5+
- "bug"
6+
- "needs-triage"
7+
body:
8+
- type: textarea
9+
id: bug-description
10+
attributes:
11+
label: Bug Description
12+
description: A clear and concise description of what the bug is.
13+
placeholder: "When I try to..."
14+
validations:
15+
required: true
16+
17+
- type: textarea
18+
id: steps-to-reproduce
19+
attributes:
20+
label: Steps to Reproduce
21+
description: Please provide numbered steps to reproduce the bug.
22+
placeholder: |
23+
1. Run 'contextatlas search...'
24+
2. Click on...
25+
3. See error...
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: expected-behavior
31+
attributes:
32+
label: Expected Behavior
33+
description: What you expected to happen.
34+
placeholder: "I expected to see..."
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: actual-behavior
40+
attributes:
41+
label: Actual Behavior
42+
description: What actually happened (include error messages if applicable).
43+
placeholder: "Instead, I got this error:..."
44+
validations:
45+
required: true
46+
47+
- type: input
48+
id: contextatlas-version
49+
attributes:
50+
label: ContextAtlas Version
51+
description: What version of ContextAtlas are you using? Run 'contextatlas --version'
52+
placeholder: "1.0.0"
53+
validations:
54+
required: false
55+
56+
- type: input
57+
id: nodejs-version
58+
attributes:
59+
label: Node.js Version
60+
description: What version of Node.js are you using? Run 'node --version'
61+
placeholder: "v20.0.0"
62+
validations:
63+
required: false
64+
65+
- type: dropdown
66+
id: operating-system
67+
attributes:
68+
label: Operating System
69+
description: What operating system are you using?
70+
options:
71+
- Linux
72+
- macOS
73+
- Windows
74+
validations:
75+
required: false
76+
77+
- type: dropdown
78+
id: usage-mode
79+
attributes:
80+
label: Usage Mode
81+
description: How are you using ContextAtlas?
82+
options:
83+
- CLI
84+
- MCP Server
85+
- Both
86+
validations:
87+
required: false
88+
89+
- type: textarea
90+
id: additional-context
91+
attributes:
92+
label: Additional Context
93+
description: Any other relevant information, logs, or screenshots about the bug.
94+
placeholder: "Here are the logs..."
95+
validations:
96+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Documentation
4+
url: https://github.com/codefromkarl/ContextAtlas/tree/main/docs
5+
about: Check the documentation before opening an issue.
6+
- name: Question / Discussion
7+
url: https://github.com/codefromkarl/ContextAtlas/discussions
8+
about: Ask questions and discuss with the community.

0 commit comments

Comments
 (0)