Skip to content

Commit 1f5ce6e

Browse files
author
Anass Rach
committed
Update CONTRIBUTING.md!
1 parent b74799d commit 1f5ce6e

2 files changed

Lines changed: 183 additions & 16 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 182 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,202 @@
11
# Contributing to Java 21 OCP Flashcards
22

3-
Thank you for your interest in contributing!
3+
Thank you for your interest in contributing to this project! This guide will help you get started with adding flashcards, quiz questions, and running the project locally.
4+
5+
## Quick Start
6+
7+
### Prerequisites
8+
- Ruby (3.0+)
9+
- Bundler gem
10+
- Git
11+
12+
### Running Locally
13+
```bash
14+
# Clone the repository
15+
git clone https://github.com/Anasss/java21docCards.git
16+
cd java21docCards
17+
18+
# Install dependencies
19+
bundle install
20+
21+
# Start the development server
22+
bundle exec jekyll serve
23+
24+
# Open your browser to http://localhost:4000/java21docCards/
25+
```
426

527
## Adding New Flashcards
628

7-
1. Choose the appropriate category directory under `_flashcards/`
8-
2. Create a new file using the naming convention: `##-descriptive-name.md`
9-
3. Use the template in `_templates/flashcard-template.md`
10-
4. Test locally with `bundle exec jekyll serve`
29+
### 1. Choose the Right Category
30+
Place your flashcard in the appropriate directory:
31+
- `_flashcards/collections/` - Collections & Generics
32+
- `_flashcards/java21-features/` - Java 21 Features
33+
- `_flashcards/streams/` - Streams & Functional Programming
34+
- `_flashcards/oop/` - Object-Oriented Programming
35+
- `_flashcards/exceptions/` - Exception Handling
36+
- And other category directories...
37+
38+
### 2. Create Your Flashcard File
39+
Use the naming convention: `##-descriptive-name.md`
40+
41+
Example: `15-pattern-matching-switch.md`
42+
43+
### 3. Use This Template
44+
```markdown
45+
---
46+
title: "Your Concept Title"
47+
category: "Category Name"
48+
order: 15
49+
tags: ["relevant", "tags", "here"]
50+
learning_tip: "A memorable tip to remember this concept"
51+
---
52+
53+
## 🃏 Your Concept Title
54+
55+
**Rule:** A clear statement of the key principle.
56+
57+
Brief explanation of what this concept does and why it matters.
58+
59+
### Code Example
60+
```java
61+
// Show practical usage with comments
62+
public class Example {
63+
public void demonstrate() {
64+
// Explain key parts
65+
System.out.println("Clear example");
66+
}
67+
}
68+
```
69+
70+
**Learning Tip:** A memorable way to remember this concept.
71+
72+
**Q:** A common question about this topic?
73+
**A:** A clear, helpful answer.
74+
```
75+
76+
### 4. Test Your Changes
77+
```bash
78+
# Run locally to verify your flashcard displays correctly
79+
bundle exec jekyll serve
80+
81+
# Check that:
82+
# - Your flashcard appears in the correct category
83+
# - Navigation works between cards
84+
# - Code examples are properly formatted
85+
# - No Jekyll build errors
86+
```
1187

1288
## Adding Quiz Questions
1389

14-
Add questions to `_data/quiz/questions.yml` following the existing format:
90+
### Add to the Question Database
91+
Edit `_data/quiz/questions.yml` and add your question:
1592

1693
```yaml
17-
- question: "Your question text?"
94+
- question: "Your question text here?"
95+
code: |
96+
// Optional code block
97+
public class Example {
98+
public static void main(String[] args) {
99+
System.out.println("Code example");
100+
}
101+
}
18102
options:
19103
- "Option A"
20104
- "Option B"
21105
- "Option C"
22106
- "Option D"
23-
correct: 1 # 0-based index
24-
explanation: "Explanation of the correct answer"
107+
correct: 1 # 0-based index (B is correct)
108+
explanation: "Clear explanation of why this answer is correct and others are wrong."
25109
category: "Category Name"
26110
```
27111
28-
## Guidelines
112+
## Content Guidelines
113+
114+
### Writing Style
115+
- Use clear, practical examples that compile and run
116+
- Include both correct and incorrect usage patterns
117+
- Provide memorable learning tips or mnemonics
118+
- Focus on exam-relevant scenarios
119+
120+
### Code Examples
121+
- Must be syntactically correct Java code
122+
- Include helpful comments explaining key concepts
123+
- Show realistic use cases, not contrived examples
124+
- Use ✅ and ❌ to indicate good vs bad practices
125+
126+
### Learning Tips
127+
- Create memorable phrases or acronyms
128+
- Use analogies that help explain complex concepts
129+
- Highlight common pitfalls or exam traps
130+
131+
## File Organization
132+
133+
### Directory Structure
134+
```
135+
_flashcards/
136+
├── collections/ # Collections & Generics
137+
├── datetime/ # Date, Time & Localization
138+
├── enums/ # Enums
139+
├── exceptions/ # Exception Handling
140+
├── io/ # I/O and NIO
141+
├── java21-features/ # Java 21 Features
142+
├── math/ # Math, Arrays, Wrappers
143+
├── modules/ # Modules & Migration
144+
├── oop/ # OOP and Encapsulation
145+
└── streams/ # Streams & Functional
146+
```
147+
148+
### Naming Convention
149+
- Use numbers with gaps: `05-`, `10-`, `15-` (allows easy insertion)
150+
- Use descriptive names: `pattern-matching-switch.md`
151+
- Keep filenames lowercase with hyphens
152+
153+
## Submission Process
154+
155+
### Before Submitting
156+
- [ ] Test locally with `bundle exec jekyll serve`
157+
- [ ] Verify all code examples work
158+
- [ ] Check spelling and grammar
159+
- [ ] Ensure consistent formatting
160+
- [ ] Add appropriate tags and learning tips
161+
162+
### Pull Request Guidelines
163+
1. **Fork the repository** on GitHub
164+
2. **Create a feature branch**: `git checkout -b add-flashcard-topic-name`
165+
3. **Make your changes** and test locally
166+
4. **Commit with clear message**: `feat: Add flashcard for Optional operations`
167+
5. **Push to your fork**: `git push origin add-flashcard-topic-name`
168+
6. **Create a Pull Request** with description of what you added
169+
170+
### PR Description Template
171+
```markdown
172+
## Summary
173+
Brief description of what this PR adds or changes.
174+
175+
## Type of Change
176+
- [ ] New flashcard(s)
177+
- [ ] New quiz question(s)
178+
- [ ] Bug fix
179+
- [ ] Documentation update
180+
181+
## Testing
182+
- [ ] Tested locally with `bundle exec jekyll serve`
183+
- [ ] All code examples compile and run correctly
184+
- [ ] No Jekyll build errors
185+
```
186+
187+
## Getting Help
188+
189+
- **Issues**: Create a GitHub issue for bugs or feature requests
190+
- **Discussions**: Use GitHub Discussions for questions about contributing
191+
- **Documentation**: Check existing flashcards for examples
192+
193+
## Recognition
194+
195+
Contributors will be acknowledged in:
196+
- GitHub contributor list
197+
- Project documentation
198+
- Release notes for significant contributions
29199

30-
- Use clear, practical examples
31-
- Include explanations for all concepts
32-
- Follow existing formatting patterns
33-
- Test code examples before submitting
200+
---
34201

35-
See the full contribution guide for detailed instructions.
202+
**Ready to contribute?** Start by running the project locally, then pick a Java concept that needs a flashcard and create your first contribution!

‎index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ A structured collection of flashcards to help you prepare for the Java 21 OCP ce
4242

4343
## 🤝 Contributing
4444

45-
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to:
45+
We welcome contributions! Check out our [contributing guide](https://github.com/Anasss/java21docCards/blob/main/CONTRIBUTING.md) for details on how to:
4646

4747
- Add new flashcards
4848
- Improve existing content

0 commit comments

Comments
 (0)