java/CONTRIBUTING.md

Contribution Guidelines

First and most importantly of all: Thank you for your interest in contributing to the Awesome Java list!

Automated Workflow

This repository uses an automated workflow to maintain the main README.md file. Here's how it works:

For Contributors

1. Edit CONTRIBUTE_README.md - Make all your changes to this file, not README.md
2. Submit a Pull Request - Create a PR with your changes to CONTRIBUTE_README.md
3. GitHub Actions will automatically:
   • Convert the list format to HTML tables
   • Add GitHub stars and last commit badges
   • Update README.md with the converted content
   • Commit and push the changes

What NOT to do

• Don't edit README.md directly - It will be overwritten by the automated workflow
• Don't edit the scripts unless you're improving the conversion process
• Don't manually run the conversion scripts - GitHub Actions handles this

How to Contribute

Adding a New Project

1. Find the appropriate section in CONTRIBUTE_README.md
2. Add your entry using this format:

   - [Project Name](https://github.com/user/repo) - Brief description of what the project does.
   

3. Follow the existing style
4. Submit a Pull Request

Updating an Existing Project

1. Find the project in CONTRIBUTE_README.md
2. Update the description or URL as needed
3. Submit a Pull Request with your changes

Adding a New Category

1. Add the category to the Contents section
2. Create a new section with the appropriate heading
3. Add projects to the new section
4. Submit a Pull Request with your changes

Guidelines

Project Requirements

• Must be Java-related - The project should be primarily for Java development
• Must be actively maintained - Recent commits and releases
• Must be useful - Provide value to Java developers

Description Guidelines

• Be concise - Keep descriptions on point
• Be descriptive - Explain what the project does and why it's useful
• Be accurate - Ensure the description matches the current project state
• Use proper grammar - Write in clear, professional English

Format Guidelines

• Use consistent formatting - Follow the existing style
• Maintain alphabetical order - Within each section
• Use proper markdown - Follow the established patterns
• Include relevant links - Link to GitHub repositories when possible

Workflow Details

GitHub Actions Workflow

The automated workflow (update-readme.yml) runs when:

• Push to master - When CONTRIBUTE_README.md or scripts are updated
• Pull Request - When CONTRIBUTE_README.md or scripts are modified
• Manual trigger - Can be triggered manually from the Actions tab

File Structure

├── CONTRIBUTE_README.md    # Source file (edit this)
├── README.md              # Generated file (don't edit)
├── scripts/
│   ├── run_workflow.java           # Main workflow orchestrator
│   ├── step_1_validate_input.java  # Input validation
│   ├── step_2_parse_projects.java  # Project parsing
│   ├── step_3_generate_badges.java # Badge generation
│   ├── step_4_generate_tables.java # HTML table generation
│   ├── step_5_assemble_readme.java # Final assembly
│   ├── step_6_validate_transformation.java # Data integrity validation
│   ├── ProjectEntry.java           # Data model
│   ├── FileUtils.java              # Utility functions
│   ├── Constants.java              # Shared constants
│   └── README.md                   # Script documentation
├── .tmp/                          # Temporary files (auto-generated)
│   ├── parsed-projects.txt
│   ├── github-badges.txt
│   └── generated-tables.html
└── .github/workflows/
    └── update-readme.yml           # GitHub Actions workflow

Workflow Process

The README generation follows a 6-step modular process:

1. Step 1 - Input Validation (step_1_validate_input.java)

   • Validates that CONTRIBUTE_README.md exists and is readable
   • Provides file statistics

2. Step 2 - Project Parsing (step_2_parse_projects.java)

   • Parses markdown content to extract project entries
   • Handles multi-line descriptions
   • Outputs: parsed-projects.txt

3. Step 3 - Badge Generation (step_3_generate_badges.java)

   • Generates GitHub badges for repositories
   • Creates stars and last-commit badges
   • Outputs: github-badges.txt

4. Step 4 - Table Generation (step_4_generate_tables.java)

   • Combines parsed projects with badges
   • Generates HTML tables with proper styling
   • Outputs: generated-tables.html

5. Step 5 - Final Assembly (step_5_assemble_readme.java)

   • Combines original content with generated tables
   • Produces the final README.md

6. Step 6 - Validation (step_6_validate_transformation.java)

   • Validates that all entries from original are present in transformed README
   • Ensures entries are in the correct sections
   • Reports missing entries, wrong sections, and extra entries

Running the Workflow

Complete Workflow:

java --enable-preview --source 25 scripts/run_workflow.java

Individual Steps:

java --enable-preview --source 25 scripts/run_workflow.java [step_number]

Direct Step Execution:

java --enable-preview --source 25 scripts/step_1_validate_input.java
java --enable-preview --source 25 scripts/step_2_parse_projects.java
# ... etc

🐛 Troubleshooting

Common Issues

1. Workflow fails - Check the Actions tab for error details
2. Badges not showing - Ensure the repository URL is correct
3. Formatting issues - Check that your markdown is valid
4. Validation fails - Step 6 validates data integrity:
   • Missing entries: Projects in original but not in final README
   • Wrong sections: Projects in different sections than expected
   • Extra entries: Projects in final README but not in original
5. Section mapping issues - Ensure projects are in the correct sections

Getting Help

• Open an issue - For questions or problems
• Check existing issues - Your question might already be answered
• Review the workflow logs - In the Actions tab

📄 License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.

---

Remember: Always edit CONTRIBUTE_README.md, never README.md directly!