Skip to content

Commit 18f8ca0

Browse files
SomeshdiwanSomeshdiwan
committed
Check This CONTRIBUTING.md
Signed-off-by: https://github.com/Someshdiwan <[email protected]>
1 parent fcbf599 commit 18f8ca0

File tree

1 file changed

+204
-42
lines changed

1 file changed

+204
-42
lines changed

‎CONTRIBUTING.md‎

Lines changed: 204 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,242 @@
1-
# Contribution Guidelines
1+
# Contributing to JavaEvolution — Learning, Growing, Mastering
22

3-
If you fork or modify this repository, please give credit to the original author: **Somesh Diwan**.
3+
Thank you for wanting to contribute! This project exists to help learners understand Java through **clear examples, practical explanations, and polished documentation**. Whether you’re fixing a typo, adding an example, improving site content, or contributing tooling — your work matters. 🌱
44

5-
For any significant modifications, a reference back to the original repository is appreciated.
5+
---
6+
7+
## ⚖️ License & Attribution
8+
9+
This repository and all its contents are **Copyright (c) 2025 Somesh Diwan. All rights reserved.**
10+
11+
If you fork, adapt, or redistribute any part of this repository, **you must include this exact attribution line** in your fork’s `README.md`, documentation files, or code comments:
12+
13+
```
14+
Original Author: Somesh Diwan
15+
```
16+
17+
Failure to provide this attribution is a violation of the license terms.
618

719
---
820

9-
## 🚀 How to Contribute
21+
## 📖 Table of Contents
22+
- [What to Contribute](#what-to-contribute)
23+
- [Getting Started (Local Setup)](#getting-started-local-setup)
24+
- [Branching & Workflow](#branching--workflow)
25+
- [Commit Message Format](#commit-message-format)
26+
- [Testing Locally](#testing-locally)
27+
- [Quality Checklist](#quality-checklist-before-opening-pr)
28+
- [Pull Request & Review Process](#pull-request--review-process)
29+
- [Code Style & Best Practices](#code-style--best-practices)
30+
- [Communication & Etiquette](#communication--etiquette)
31+
- [Contributor Code of Conduct](#contributor-code-of-conduct)
32+
- [Contact / Support](#contact--support)
1033

11-
### 1. Fork the Repository
12-
Visit the GitHub repo and click the **"Fork"** button.
34+
---
35+
36+
## 💡 What to Contribute
37+
Helpful contributions include:
38+
- New or improved **Java example files** (`.java`) in the correct section folders.
39+
- Explanatory files (`.md`, `.txt`) accompanying examples.
40+
- Fixes: typos, unclear wording, or broken examples.
41+
- Site improvements under `site/` (Jekyll pages, assets, docs).
42+
- Tests, utilities, or tooling that make examples easier to run.
43+
- Advanced content: concurrency, streams, design patterns, or integration with databases.
44+
- Translations, diagrams, or supplementary learning material.
45+
46+
👉 If you’re unsure where a change belongs, open an issue and label it `help wanted`.
47+
48+
---
49+
50+
## 🛠️ Getting Started (Local Setup)
1351

14-
### 2. Clone Locally
52+
Suggested workspace folder name: `Java Se`.
53+
54+
**macOS / Linux**
1555
```bash
16-
git clone https://github.com/Someshdiwan/JavaEvolution-Learning-Growing-Mastering.git
56+
mkdir -p ~/Projects/"Java Se"
57+
cd ~/Projects/"Java Se"
1758
```
1859

19-
### 3. Make Changes
20-
- **Java Code Examples:** Add new examples to directories like `Section*` (e.g., `Section10Methods`, `JAVA8`).
21-
- **Website Enhancements:** Update files inside the `site/` directory (e.g., `index.md`, `style.css`, `_layouts/default.html`).
22-
- Ensure your contributions align with the goal of offering a structured Java learning experience.
60+
**Windows (PowerShell)**
61+
```powershell
62+
mkdir "C:\Users\<YourName>\Projects\Java Se"
63+
cd "C:\Users\<YourName>\Projects\Java Se"
64+
```
2365

24-
### 4. Submit a Pull Request
25-
- Push your changes to your forked repository.
26-
- Open a pull request (PR) to the original repository.
27-
- Include a clear description of the changes you’ve made.
66+
Clone your fork:
67+
```bash
68+
git clone https://github.com/<your-username>/JavaEvolution-Learning-Growing-Mastering.git
69+
cd JavaEvolution-Learning-Growing-Mastering
70+
```
2871

29-
---
72+
Add upstream remote:
73+
```bash
74+
git remote add upstream https://github.com/Someshdiwan/JavaEvolution-Learning-Growing-Mastering.git
75+
```
3076

31-
## 🖥️ Setup Guide
77+
### ✅ Prerequisites
78+
- Git (latest stable)
79+
- Java JDK (8+ depending on the section) → Check with `java -version`
80+
- Optional: Maven or Gradle
81+
- Optional: Jekyll (if working on `site/`)
82+
- IDE: IntelliJ IDEA, VS Code, or Eclipse
3283

33-
To run the project locally and test your contributions:
84+
---
3485

35-
### 1. Clone the Repository
86+
## 🌱 Branching & Workflow
87+
- Always create a new branch per feature/fix:
88+
```bash
89+
git checkout -b feat/<topic>-short-description
90+
```
91+
- Regularly sync with upstream `main` to avoid conflicts:
3692
```bash
37-
git clone https://github.com/Someshdiwan/JavaEvolution-Learning-Growing-Mastering.git
93+
git fetch upstream
94+
git rebase upstream/main # or `merge` if preferred
3895
```
96+
- Push to your fork:
97+
```bash
98+
git push origin feat/<topic>-short-description
99+
```
100+
- Open a Pull Request against `main` with a clear description.
101+
102+
---
103+
104+
## 📝 Commit Message Format
105+
Follow a **structured commit message style** to keep history clear.
106+
107+
### Supported Types
108+
| Type | Purpose |
109+
|------------|---------|
110+
| `feat` | New feature/example |
111+
| `fix` | Bug fix |
112+
| `docs` | Documentation updates |
113+
| `style` | Formatting, missing semicolons, whitespace |
114+
| `refactor` | Code changes without feature/bug impact |
115+
| `perf` | Performance improvement |
116+
| `test` | Adding/updating tests |
117+
| `chore` | Build process, dependencies, tooling |
118+
| `ci` | Continuous Integration changes |
119+
120+
### Format
121+
```
122+
<type>(scope): short summary
123+
124+
What
125+
- Bullet list of changes.
39126
40-
### 2. Install Jekyll
41-
Follow the [Jekyll Installation Guide](https://jekyllrb.com/docs/installation/) to set it up on your system.
127+
Why
128+
- Reason for the change.
42129
43-
### 3. Navigate to the `site/` Directory
130+
How / Logic
131+
- Key details or design decisions.
132+
133+
Testing / Notes
134+
- How you tested, limitations, or notes for reviewers.
135+
```
136+
137+
**Short Example:**
138+
```
139+
fix(inheritance): correct typo in class name
140+
```
141+
142+
**Detailed Example:**
143+
```markdown
144+
feat(jdbc): add prepared statement example
145+
146+
What
147+
- Added PreparedStatement demo in `Section28JDBCusingSQLite/JDBCProgram`.
148+
- Updated explanation text file.
149+
150+
Why
151+
- Learners need secure, parameter-bound SQL examples.
152+
153+
How / Logic
154+
- Used try-with-resources and parameter binding.
155+
- Added comments for clarity.
156+
157+
Testing / Notes
158+
- Ran manually with SQLite DB; validated output.
159+
```
160+
161+
---
162+
163+
## 🧪 Testing Locally
164+
165+
### Java Examples
44166
```bash
45-
cd JavaEvolution-Learning-Growing-Mastering/site
167+
javac -d out src/Section12Inheritance/YourExample.java
168+
java -cp out Section12Inheritance.YourExample
46169
```
170+
Ensure examples compile and run without missing dependencies.
47171

48-
### 4. Run the Server
172+
### Documentation / Site
49173
```bash
174+
cd site
50175
jekyll serve
51176
```
52177

53-
### 5. View the Site
54-
Open your browser and go to:
55-
```
56-
http://localhost:4000
178+
### JUnit Tests (if available)
179+
```bash
180+
mvn test
181+
# or
182+
gradle test
57183
```
58184

59185
---
60186

61-
## 🛠️ Contribution Best Practices
187+
## ✅ Quality Checklist (Before Opening PR)
188+
- [ ] Code compiles without errors/warnings.
189+
- [ ] Example is runnable and documented.
190+
- [ ] Commit message follows format.
191+
- [ ] Attribution included when adapting external content.
192+
- [ ] Tests updated/added if relevant.
193+
194+
---
62195

63-
- **Code Quality:** Ensure your Java files compile correctly and are well-commented for educational clarity.
64-
- **Documentation:** Update `Explaination.md` or related `.md` files with explanations of your additions.
65-
- **Testing:** Always test your changes locally using the Jekyll server before submitting.
66-
- **Credit:** Cite external sources properly if you’ve used any.
67-
- **Consistency:** Match the existing structure and naming conventions (`.java`, `.txt`, `.iml`).
196+
## 🔄 Pull Request & Review Process
197+
- Open a PR against `main` with a **clear title** and **description**.
198+
- Link related issues (if any).
199+
- Draft PRs are welcome for early feedback.
200+
- Reviewer may request changes → respond & push updates.
201+
- Once approved, maintainers will merge.
68202

69203
---
70204

71-
## ✅ Review Process
205+
## 🎯 Code Style & Best Practices
206+
- Prefer **clear, self-explanatory examples** over clever tricks.
207+
- Add comments where a learner may struggle.
208+
- Keep methods **short & focused**.
209+
- Avoid large external dependencies for single examples.
210+
- Always use `try-with-resources` for I/O and DB examples.
211+
- Consistent formatting → auto-format with IDE before committing.
72212

73-
- Pull requests are reviewed by the maintainers.
74-
- You may receive feedback to help align your contribution with the project's educational objectives.
75-
- Once approved, your changes will be merged into the main branch.
213+
---
214+
215+
## 🤝 Communication & Etiquette
216+
- Be respectful and patient in discussions.
217+
- Ask questions openly if unsure.
218+
- Small, incremental PRs are easier to review.
219+
- Assume good intent; focus on learning and collaboration.
76220

77221
---
78222

79-
Thank you for contributing to **JavaEvolution**!
80-
Your efforts help create a better resource for Java learners everywhere. 🌱
223+
## 📜 Contributor Code of Conduct
224+
By participating in this project, you agree to:
225+
- Treat everyone with respect and kindness.
226+
- Provide constructive feedback.
227+
- Avoid harassment, discrimination, or offensive behavior.
228+
- Foster an inclusive and supportive learning community.
229+
230+
Violations may result in being blocked from contributions.
231+
232+
---
233+
234+
## 📬 Contact / Support
235+
If you have questions before contributing, open an issue with the `question` label.
236+
237+
---
238+
239+
## 🙏 Thank You!
240+
Your contributions make JavaEvolution better for learners worldwide. Keep examples **clear, well-documented, and focused on teaching.** 🚀
241+
242+
---

0 commit comments

Comments
 (0)