[DOCS]: Comprehensive Documentation Improvement

[fernandonevarez]

Description

Enhance the project's documentation to improve clarity for contributors and ensure a professional, well-structured Git flow. This includes adding more detailed issue templates, clarifying contributor guidelines, and updating the branching model to include hotfix branches.

Proposed Documentation Improvements

1. Issue Templates

• Add additional issue templates to accommodate various types of issues, such as Bug Reports, Feature Requests, Hotfix Requests, Documentation Updates, and Refactor Requests.
• Ensure that each template includes clear instructions and prompts contributors for all necessary information.
• Examples:
  • Refactor Request: Include fields for "Current Code", "Proposed Refactoring", and "Benefits".
  • Hotfix Request: Include fields for "Issue Description", "Impact on Users", and "Urgency Level".
  • Documentation Update: Include fields for "Section to Update", "Suggested Changes", and "Reason for Update".

2. Contributor Guidelines

• Expand on the existing contributor guidelines to provide greater clarity around contribution processes, including setting up the project locally, coding standards, and the pull request process.
• Add a specific section on testing requirements and best practices for contributors.
• Examples:
  • Coding Standards: Include code style conventions (e.g., indentation, naming conventions) with examples to illustrate the preferred style.
  • Example: "Use camelCase for variable names (e.g., userAuthentication), and PascalCase for component names (e.g., UserProfile)."
  • Pull Request Process: Outline the steps for creating a pull request, including linking related issues (e.g., "Closes #123"), requesting reviews from CODEOWNERS, and addressing feedback.
  • Example: "After making changes, push your branch and open a pull request to dev. Ensure to include Closes #issue-number in the PR description."
• Code Review Checklist: Add a section to provide a detailed checklist for reviewers to standardize the code review process and ensure quality.
  • Example Checklist:
  • Ensure that the code follows the project's style guide.
  • Verify that new features include appropriate tests.
  • Check for clear and concise comments where needed.

3. Branching Model Update

• Update the Branching Model section to include a hotfix branch for addressing urgent issues in production.
• Hotfix Branch Details:
  • Purpose: To resolve urgent production issues.
  • Branch Creation: Should branch off from main and be merged back into both main and dev after completion.
  • Naming Convention: Use the prefix hotfix/ followed by a brief description (e.g., hotfix/fix-critical-bug).
  • Example: If there's a login issue in production, the branch could be named hotfix/fix-login-bug.

4. Commit Message Guidelines

• Ensure commit messages follow a consistent format that is action-oriented and descriptive. Encourage the use of Conventional Commits to maintain readability and traceability.
• Example Structure:

     <type>[optional scope]: <description>
     [optional body]
     [optional footer(s)

• Add Example Commit Messages:
  • "fix(auth): resolve login issue on production"
  • "feat(ui): add new footer component"

5. Git Flow Best Practices

• Include a more detailed explanation of the project's Git flow practices for contributors. This includes how to create branches, submit pull requests, resolve merge conflicts, and follow the appropriate merge strategy.
• Example: Describe how to create a feature branch using git checkout -b feat/new-feature and how to keep it updated with dev by regularly rebasing or merging.

6. Release Process

• Document the release process, including how and when versions are tagged, the criteria for merging into main, and how to handle versioning.
• Example: Use semantic versioning (e.g., v1.2.3) and outline the steps for tagging a release (git tag -a v1.2.3 -m "Release v1.2.3").

Additional Information

• The documentation changes should be made in the Contributing Guidelines.
• Aim to make the documentation clear, concise, and welcoming to new contributors while maintaining a high standard for contributions.

[fernandonevarez]

Suggestion: Enable GitHub Discussions for Documentation Improvements

As I’m working on improving the documentation, I’m thinking it might be a good idea to enable GitHub Discussions for this repo. Even though I’m working solo right now, having Discussions enabled would provide a dedicated space for future feedback and conversations around documentation updates.

Once enabled, I plan to start a thread for Comprehensive Documentation Improvements. This would not only help keep track of my progress but also allow for easier collaboration and input down the line.

This issue moving forward will be opened and closed as needed based on what's said in the corresponding discussion's thread.