Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
488 lines (349 loc) · 9.9 KB

CONTRIBUTING.md

File metadata and controls

488 lines (349 loc) · 9.9 KB

Contributing to Java Learning Repository

Thank you for your interest in contributing to this Java learning resource! This document provides guidelines for contributing.

📋 Table of Contents

🤝 Code of Conduct

Our Standards

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn
  • Maintain professionalism

Unacceptable Behavior

  • Harassment or discrimination
  • Trolling or insulting comments
  • Publishing others' private information
  • Any unprofessional conduct

💡 How Can I Contribute?

1. Reporting Issues

Found a bug or error?

  • Check if it's already reported
  • Create a clear, descriptive title
  • Provide steps to reproduce
  • Include expected vs actual behavior
  • Add screenshots if applicable

Documentation improvements:

  • Typos or grammatical errors
  • Unclear explanations
  • Missing information
  • Outdated content

2. Suggesting Enhancements

New topics or examples:

  • Explain why it would be valuable
  • Provide reference materials
  • Describe expected implementation

Improvements to existing content:

  • What could be better
  • Why the change is needed
  • Proposed solution

3. Code Contributions

Java Examples:

  • Additional examples for existing topics
  • Alternative implementations
  • Performance optimizations
  • Edge case handling

Documentation:

  • More detailed explanations
  • Additional code comments
  • Better examples
  • Interview questions

📝 Style Guidelines

Documentation Standards

README Files

# Topic Name

## 📘 Overview
Brief description of the topic

## 🔑 Key Concepts
- Concept 1
- Concept 2

## 📝 Syntax
```java
// Code example

💻 Code Examples

[Examples with explanations]

✅ Best Practices

[Do's and don'ts]

🎓 Interview Questions

[Common questions]


#### Markdown Formatting

- Use headers hierarchically (`#`, `##`, `###`)
- Use code blocks with language specification
- Include emojis for visual clarity
- Use tables for structured data
- Keep lines under 100 characters (when practical)
- Use relative links for internal references

### Java Code Standards

#### File Structure

```java
/**
 * TopicName Examples
 * @author GitHub Copilot
 * @topic Module - Topic Name
 */
public class TopicNameExample {
    
    public static void main(String[] args) {
        System.out.println("=== TOPIC NAME EXAMPLES ===\n");
        
        example1();
        example2();
        
        System.out.println("\n=== Complete! ===");
    }
    
    /**
     * Example 1: What it demonstrates
     * Time Complexity: O(?)
     * Space Complexity: O(?)
     */
    static void example1() {
        System.out.println("--- Example 1 Description ---");
        
        // Step 1: Clear explanation
        // code
        
        // Step 2: Clear explanation
        // code
        
        System.out.println("Result: " + result);
        System.out.println();
    }
    
    // More example methods...
}

Code Quality Requirements

  • ✅ Compiles without errors or warnings
  • ✅ Runs successfully with clear output
  • ✅ 5-8 example methods minimum
  • ✅ Comprehensive comments (1:2 ratio)
  • ✅ Demonstrates real-world use cases
  • ✅ Proper exception handling
  • ✅ Clear variable names
  • ✅ Consistent formatting

Naming Conventions

// Classes: PascalCase
public class MyExample { }

// Methods: camelCase
public void myMethod() { }

// Variables: camelCase
int myVariable = 0;

// Constants: UPPER_SNAKE_CASE
public static final int MAX_SIZE = 100;

// Packages: lowercase
package com.example.module;

Comment Standards

// Single-line comments for brief explanations

/**
 * Multi-line JavaDoc for:
 * - Classes
 * - Public methods
 * - Complex logic
 */

// Step-by-step comments
// Step 1: Initialize data structure
List<String> list = new ArrayList<>();

// Step 2: Add elements
list.add("example");

🔄 Submission Process

1. Fork the Repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/JAVA.git
cd JAVA

2. Create a Branch

# Use descriptive branch names
git checkout -b feature/new-topic-example
git checkout -b fix/typo-in-readme
git checkout -b docs/improve-multithreading-guide

3. Make Your Changes

For New Topics

  1. Create folder following numbering convention
  2. Add README.md with complete documentation
  3. Add Java example file with 5-8 methods
  4. Update module INDEX.md
  5. Update module README.md if needed

For Improvements

  1. Make focused, specific changes
  2. Update related documentation
  3. Ensure examples still compile and run
  4. Update comments if code changes

4. Test Your Changes

# Compile Java files
javac YourExample.java

# Run to verify output
java YourExample

# Check for errors
# Verify all links work
# Ensure formatting is consistent

5. Commit Your Changes

# Use clear, descriptive commit messages
git add .
git commit -m "Add: New example for Optional class in Lambdas module"
git commit -m "Fix: Correct typo in Streams API README"
git commit -m "Improve: Add performance comparison to HashMap example"

Commit Message Format:

Type: Brief description

Detailed explanation if needed
- Bullet points for multiple changes
- Reference issue numbers: #123

Types:

  • Add: New feature or content
  • Fix: Bug fix or correction
  • Update: Modify existing content
  • Improve: Enhance existing content
  • Remove: Delete outdated content
  • Docs: Documentation only changes

6. Push and Create Pull Request

# Push to your fork
git push origin feature/your-branch-name

Then create a Pull Request on GitHub with:

  • Clear title describing the change
  • Description explaining what and why
  • Testing steps you performed
  • Screenshots if applicable
  • Related issues if any

✅ Quality Standards

Documentation Checklist

  • No spelling or grammatical errors
  • Clear and concise explanations
  • Code examples are correct
  • Links work properly
  • Formatting is consistent
  • Emojis used appropriately
  • Tables formatted correctly

Code Checklist

  • Compiles without errors
  • Runs successfully
  • Produces expected output
  • Well-commented
  • Follows naming conventions
  • Proper exception handling
  • No hardcoded values (where appropriate)
  • Clear method names
  • Consistent indentation (4 spaces)

Module Integration Checklist

  • Topic follows numbering convention
  • README structure matches other topics
  • Java example follows template
  • Module INDEX.md updated
  • Module README.md updated
  • Cross-references added
  • Navigation links work

📚 Content Guidelines

What We're Looking For

✅ High Quality:

  • Production-ready code
  • Comprehensive explanations
  • Real-world examples
  • Best practices
  • Common pitfalls

✅ Educational Value:

  • Clear learning progression
  • Builds on previous topics
  • Practical applications
  • Interview relevance

✅ Completeness:

  • Thorough documentation
  • Multiple examples
  • Edge cases covered
  • Performance considerations

What We're Not Looking For

❌ Low Quality:

  • Incomplete examples
  • Poor explanations
  • Copy-pasted code without understanding
  • Untested code

❌ Out of Scope:

  • Framework-specific code (Spring, Hibernate, etc.)
  • Build tool configurations
  • IDE-specific content
  • Third-party library tutorials

🎯 Priority Areas

High Priority

  1. Additional Examples for existing topics
  2. Interview Questions for each topic
  3. Performance Comparisons where applicable
  4. Best Practices documentation
  5. Common Pitfalls sections

Medium Priority

  1. More detailed explanations
  2. Additional code comments
  3. Cross-references between topics
  4. Visual diagrams (if applicable)

Low Priority

  1. Formatting improvements
  2. Minor typo fixes
  3. Link updates

🔍 Review Process

What Reviewers Look For

  1. Correctness

    • Code compiles and runs
    • Examples are accurate
    • Explanations are correct

  2. Quality

    • Follows style guidelines
    • Well-documented
    • Clear and understandable

  3. Completeness

    • All required sections present
    • Adequate examples
    • Proper testing

  4. Consistency

    • Matches existing structure
    • Follows naming conventions
    • Similar quality to other topics

Approval Criteria

  • ✅ Meets all quality standards
  • ✅ Compiles and runs successfully
  • ✅ Documentation is complete
  • ✅ Follows style guidelines
  • ✅ Adds value to repository

🙏 Recognition

All contributors will be acknowledged! Significant contributions may be highlighted in the repository.

📞 Questions?

  • Check existing issues
  • Review README.md for overview
  • See INDEX.md for navigation
  • Reference existing modules for examples

📄 License

By contributing, you agree that your contributions will be licensed under the same Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0) as the repository.

All contributions will be attributed to Abhinav (abhinav1602) as the repository owner.

See LICENSE for details.

🎉 Thank You!

Your contributions help make this a better learning resource for everyone. We appreciate your time and effort!

Happy Contributing! 🚀

💖 Support the Project

If you appreciate this resource and want to support its continued development:

☕ Buy me a coffee on Ko-fi

Last Updated: November 2025
Maintained By: Abhinav (abhinav1602)