Skip to content

Commit de482a7

Browse files
butschsterbutschster
authored
Merge pull request #237 from context-hub/feature/community-standards
docs: add contributing guidelines and code of conduct
2 parents 53d520e + 4c4791a commit de482a7

File tree

2 files changed

+378
-0
lines changed

2 files changed

+378
-0
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Code of Conduct
2+
3+
## Our Commitment
4+
5+
We are committed to providing a welcoming, inclusive, and professional environment for all contributors to the CTX (
6+
Context Generator) project, regardless of age, body size, disability, ethnicity, gender identity and expression, level
7+
of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
8+
9+
## Our Standards
10+
11+
### Positive Behavior
12+
13+
Examples of behavior that contributes to creating a positive environment include:
14+
15+
* Using welcoming and inclusive language
16+
* Being respectful of differing viewpoints and experiences
17+
* Gracefully accepting constructive criticism
18+
* Focusing on what is best for the community
19+
* Showing empathy towards other community members
20+
* Providing helpful and constructive feedback in code reviews
21+
* Being patient with newcomers and those learning
22+
23+
### Technical Standards
24+
25+
* Follow the coding standards outlined in CLAUDE.md and CONTRIBUTING.md
26+
* Write clean, well-documented code with appropriate tests
27+
* Use proper commit message formatting and PR descriptions
28+
* Participate constructively in code reviews and discussions
29+
* Respect the project's architecture patterns and conventions
30+
* Run quality checks (`composer cs-check`, `composer psalm`) before submitting
31+
32+
### Unacceptable Behavior
33+
34+
Examples of unacceptable behavior include:
35+
36+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
37+
* Trolling, insulting/derogatory comments, and personal or political attacks
38+
* Public or private harassment
39+
* Publishing others' private information without explicit permission
40+
* Deliberately disrupting discussions or development processes
41+
* Submitting malicious code or security vulnerabilities
42+
* Other conduct which could reasonably be considered inappropriate in a professional setting
43+
44+
## Enforcement Responsibilities
45+
46+
Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take
47+
appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive,
48+
or harmful.
49+
50+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
51+
issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for
52+
moderation decisions when appropriate.
53+
54+
## Scope
55+
56+
This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing
57+
the project or its community in public spaces. Examples of representing our project or community include using an
58+
official project e-mail address, posting via an official social media account, or acting as an appointed representative
59+
at an online or offline event.
60+
61+
## Reporting
62+
63+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by:
64+
65+
* Opening an issue in the project repository
66+
* Contacting the project maintainers directly
67+
* Using GitHub's reporting features
68+
69+
All reports will be reviewed and investigated promptly and fairly. All project maintainers are obligated to respect the
70+
privacy and security of the reporter of any incident.
71+
72+
## Enforcement Guidelines
73+
74+
Project maintainers will follow these Community Impact Guidelines in determining the consequences for any action they
75+
deem in violation of this Code of Conduct:
76+
77+
### 1. Correction
78+
79+
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the
80+
community.
81+
82+
**Consequence**: A private, written warning from project maintainers, providing clarity around the nature of the
83+
violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
84+
85+
### 2. Warning
86+
87+
**Community Impact**: A violation through a single incident or series of actions.
88+
89+
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including
90+
unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding
91+
interactions in community spaces as well as external channels like social media. Violating these terms may lead to a
92+
temporary or permanent ban.
93+
94+
### 3. Temporary Ban
95+
96+
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
97+
98+
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified
99+
period of time. No public or private interaction with the people involved, including unsolicited interaction with those
100+
enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
101+
102+
### 4. Permanent Ban
103+
104+
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
105+
behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
106+
107+
**Consequence**: A permanent ban from any sort of public interaction within the community.
108+
109+
## Attribution
110+
111+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
112+
available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
113+
114+
Community Impact Guidelines were inspired
115+
by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
116+
117+
For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq.
118+
Translations are available at https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
# Contributing
2+
3+
We're excited to welcome you as a contributor to our project!
4+
5+
## How to Contribute
6+
7+
There are many ways to contribute to **CTX**:
8+
9+
1. **Report Issues**: If you find a bug or have a
10+
suggestion, [create an issue](https://github.com/context-hub/generator/issues) on our GitHub repository.
11+
2. **Submit Pull Requests**: Have a fix or a new feature? Submit a pull request!
12+
3. **Improve Documentation**: Help us make our [documentation](https://github.com/context-hub/docs) more clear,
13+
comprehensive, and accessible.
14+
4. **Share Your Use Cases**: Let us know how you're using **CTX** in your projects.
15+
16+
We label issues that are suitable for community contribution with the `help wanted` tag. Additionally, we use labels
17+
such as `good first issue` for newcomer-friendly tasks, and complexity indicators to help you choose tasks that match
18+
your experience level.
19+
20+
## Getting Started with Contributing
21+
22+
Follow this guide to set up your environment and effectively contribute to the **CTX** project. We've designed
23+
a workflow that leverages the tool's own capabilities to help you understand and improve the codebase.
24+
25+
### 1. Set Up Your Environment
26+
27+
```bash
28+
# Fork and clone the repository
29+
git clone https://github.com/YOUR-USERNAME/context-generator.git
30+
cd context-generator
31+
32+
# Install dependencies
33+
composer install
34+
35+
# Make the CLI tool available locally
36+
chmod +x ctx
37+
38+
# Test the command
39+
./ctx --help
40+
```
41+
42+
> **Note:** Use the local `./ctx` command during development to test your changes. The globally installed`ctx` command
43+
> won't reflect your local modifications.
44+
45+
### 2. Understand the Project Structure
46+
47+
Before diving into specific components, familiarize yourself with the project structure. To get a detailed view of the
48+
project structure, use the `tree` source type:
49+
50+
```yaml
51+
documents:
52+
- description: Project File Structure
53+
outputPath: docs/file-structure.md
54+
sources:
55+
- type: tree
56+
description: Project File Structure
57+
sourcePaths:
58+
- src
59+
```
60+
61+
Run this configuration to generate a visual representation of the codebase structure:
62+
63+
```bash
64+
./ctx
65+
```
66+
67+
This will create a `docs/file-structure.md` file that outlines the project's organization. Put this file in the
68+
Claude project context to help it understand the codebase.
69+
70+
### 3. Request Specific Context Using YAML
71+
72+
When working on a specific feature or bug fix, create targeted context requests to get exactly the information you need.
73+
74+
You can also describe your task to an LLM and ask it to suggest which files might be relevant to your problem.
75+
76+
> **Tip:** If you provide a json-schema file, the LLM will be able to generate a valid context.yaml file for you.
77+
78+
```yaml
79+
# Example: Create focused context for exploring source types
80+
documents:
81+
- description: "Source Type Implementation"
82+
outputPath: "my-feature-context.md"
83+
sources:
84+
- type: file
85+
sourcePaths: [ "src/Source/FileType" ]
86+
filePattern: "*.php"
87+
- type: file
88+
sourcePaths: [ "src/Source" ]
89+
filePattern: "*Interface.php"
90+
```
91+
92+
Generate your custom context:
93+
94+
```bash
95+
./ctx
96+
```
97+
98+
This structured approach offers several advantages:
99+
100+
- **Precision**: Request only what you need without excess information
101+
- **Structure**: Use the application's own configuration format for clarity
102+
- **Progressive Discovery**: Build your understanding incrementally
103+
- **Efficiency**: Focus on relevant parts of the codebase
104+
105+
Let me enhance the section on collaborating with AI assistants to include this important recommendation:
106+
107+
### 4. Collaborate with AI Assistants
108+
109+
Share the generated context files with AI assistants like Claude to get help with:
110+
111+
- Understanding complex parts of the codebase
112+
- Designing new features
113+
- Debugging issues
114+
- Reviewing your implementation approach
115+
116+
Before diving into implementation, ask the LLM to help you generate:
117+
118+
- **Feature Request documents** for new functionality
119+
- **RFC (Request for Comments)** for architectural changes
120+
- **Bug reports** with comprehensive details
121+
- **Implementation plans** outlining the approach
122+
123+
These documents serve multiple purposes:
124+
125+
1. They help clarify your own understanding of the task
126+
2. They can be used to create GitHub issues with well-structured information
127+
3. They provide a reference document you can share in new chat sessions
128+
4. They ensure all aspects of the problem are considered before coding begins
129+
130+
For example, you might ask:
131+
132+
```yaml
133+
documents:
134+
- description: "Current Composer Source Implementation"
135+
outputPath: "composer-source-current.md"
136+
sources:
137+
- type: file
138+
sourcePaths: [ "src/Source/Composer/" ]
139+
filePattern: [ "ComposerSource.php", "ComposerSourceFetcher.php" ]
140+
```
141+
142+
**Then ask Claude:**
143+
"Based on this implementation, please generate an RFC for adding remote repository support to the Composer source.
144+
Include the problem statement, proposed solution, implementation details, and potential challenges."
145+
146+
This gives the AI assistant exactly the context needed to provide meaningful assistance with your specific task, and the
147+
resulting document becomes a valuable asset throughout your development process.
148+
149+
### 5. Implement Your Changes
150+
151+
> **Tip**: When you provide all required context to Claude, it will be able to solve your task efficiently. With proper
152+
> context, the solution will be fast, precise, and aligned with the project's patterns and standards.
153+
154+
With a solid understanding of the codebase:
155+
156+
- Create a new branch for your changes
157+
- Implement your feature or fix following these steps:
158+
1. Provide the generated context to Claude or another AI assistant
159+
2. Clearly describe what you're trying to implement
160+
3. With proper context, Claude can help generate precise, working solutions quickly
161+
4. Review the suggested implementation and adapt as needed
162+
- Add tests to verify your changes
163+
- Update or add documentation as needed:
164+
1. Provide the existing documentation section to Claude
165+
2. Ask Claude to update or rewrite the section with your changes
166+
3. Review and refine the suggested documentation
167+
4. Include the updated documentation in your pull request
168+
169+
### 6. Document Your Changes
170+
171+
If you worked with an LLM to implement your changes, ask it to help draft commit messages and pull request descriptions.
172+
173+
You can also generate a diff for your changes and ask an LLM to analyze it:
174+
175+
```yaml
176+
# Generate context for your changes
177+
documents:
178+
- description: "My Feature Implementation"
179+
outputPath: "my-changes.md"
180+
sources:
181+
- type: git_diff
182+
description: "My Changes"
183+
commit: "unstaged" # or "staged" if you've already staged your changes
184+
```
185+
186+
### 7. Code Quality Checks
187+
188+
Before submitting your pull request, ensure your code meets our quality standards:
189+
190+
#### Code Style Standards
191+
192+
- **PHP 8.3+** minimum requirement
193+
- **Strict typing**: All files must use `declare(strict_types=1)`
194+
- **camelCase** for enum cases (not SCREAMING_SNAKE_CASE)
195+
- **Namespace consistency**: Follow `Butschster\ContextGenerator\*` pattern
196+
- **Final classes**: Classes should be `final` unless designed for extension
197+
198+
#### Architecture Patterns
199+
200+
Follow these established patterns:
201+
202+
- **Immutable DTOs**: Use readonly classes and value objects
203+
- **Interface segregation**: Create clear interfaces for all major components
204+
- **Factory pattern**: Use factories for creating configured instances
205+
- **Registry pattern**: Centralize registration of sources, modifiers, etc.
206+
- **Bootloader pattern**: Follow Spiral-style service registration
207+
208+
#### Running Quality Tools
209+
210+
Run these commands to ensure code quality:
211+
212+
```bash
213+
# Check code style (dry run)
214+
composer cs-check
215+
216+
# Fix code style issues automatically
217+
composer cs-fix
218+
219+
# Run static analysis
220+
composer psalm
221+
222+
# Apply automated refactoring
223+
composer refactor
224+
225+
# Run tests
226+
composer test
227+
```
228+
229+
**Important**: Always run `composer cs-check` and `composer psalm` before submitting your PR. Fix any issues reported by
230+
these tools.
231+
232+
### 8. Submit Your Pull Request
233+
234+
- Push your changes to your fork
235+
- Open a pull request with a clear description
236+
- Include relevant context files or excerpts
237+
- Reference any related issues
238+
- Ensure all quality checks pass
239+
240+
By using **CTX** in your contribution workflow, you'll not only improve the project but also gain firsthand
241+
experience with the tool while developing more effective collaboration patterns with AI assistants.
242+
243+
## Areas Where Help Is Needed
244+
245+
We're particularly looking for help with:
246+
247+
- Adding support for additional source types
248+
- Enhancing documentation with more examples
249+
- Creating specialized content modifiers for different languages
250+
- Building integrations with popular IDEs and tools
251+
252+
Your contributions, big or small, help make **CTX** a better tool for everyone. We look forward to
253+
collaborating with you!
254+
255+
## Questions?
256+
257+
If you have any questions about contributing, feel free to open an issue labeled "question" or reach out through the
258+
[discussions](https://github.com/context-hub/generator/discussions) section on GitHub.
259+
260+
Thank you for considering contributing to **CTX**!

0 commit comments

Comments
 (0)