Contributing Guidelines

Thank you for your interest in contributing to EpiDash! This document provides guidelines and instructions for contributing to the project.

Table of Contents

• Code of Conduct
• Getting Started
• How to Contribute
• Development Process
• Pull Request Process
• Coding Standards
• Testing Guidelines
• Documentation
• Community

Code of Conduct

EpiDash is committed to providing a welcoming and inspiring community for all. Please review our Code of Conduct to understand expected behavior.

Key principles:

• Be respectful and inclusive
• Value different viewpoints and experiences
• Give and gracefully accept constructive feedback
• Focus on what is best for the community and the project

Getting Started

Prerequisites

To contribute to EpiDash, you'll need:

• Basic knowledge of HTML, CSS, JavaScript, and PHP
• Git installed on your computer
• A GitHub account
• A local development environment with PHP 7.4+ and a web server

Setting Up Development Environment

1. Fork the repository

   • Visit https://github.com/dlangkip/epidash
   • Click the "Fork" button in the upper right corner

2. Clone your fork

   git clone https://github.com/YOUR-USERNAME/epidash.git
   cd epidash
   

3. Add the original repository as upstream

   git remote add upstream https://github.com/dlangkip/epidash.git
   

4. Set up the local environment

   • Follow the instructions in the Installation Guide

5. Create a new branch for your feature or bugfix

   git checkout -b feature/your-feature-name
   # or for bugfixes
   git checkout -b fix/issue-description
   

How to Contribute

There are many ways to contribute to EpiDash:

1. Reporting Bugs

If you find a bug, please create an issue in the GitHub repository with:

• A clear, descriptive title
• Detailed steps to reproduce the bug
• Expected behavior vs. actual behavior
• Screenshots if applicable
• Any relevant code snippets or error messages
• Your environment (browser, OS, PHP version, etc.)

2. Suggesting Enhancements

For feature requests or enhancements:

• Use a clear and descriptive title
• Provide a detailed description of the suggested enhancement
• Explain why this enhancement would be useful to EpiDash users
• Include any relevant mockups or examples
• Reference related issues or documentation if applicable

3. Code Contributions

Code contributions are welcome for:

• Bug fixes
• New features aligned with the Development Roadmap
• Performance improvements
• Accessibility enhancements
• Test coverage improvements

4. Documentation Improvements

Help improve the documentation by:

• Fixing errors or outdated information
• Adding examples and clarifications
• Improving organization and structure
• Adding diagrams or visual aids

5. Design Contributions

Design contributions are valuable for:

• UI/UX improvements
• Visual design assets
• Responsive design enhancements
• Accessibility improvements

Development Process

Workflow

EpiDash follows a Git Flow-inspired workflow:

• main branch contains stable releases
• develop branch is for ongoing development
• Feature branches are created from develop
• Pull requests are merged into develop
• Releases are created by merging develop into main

Keeping Your Fork Updated

To keep your fork in sync with the original repository:

git checkout develop
git pull upstream develop
git push origin develop

Committing Changes

Follow these guidelines for commit messages:

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters
• Reference issues and pull requests after the first line
• Use conventional commit prefixes:
  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • style: for formatting changes
  • refactor: for code refactoring
  • test: for adding or modifying tests
  • chore: for maintenance tasks

Example:

feat: add age group comparison chart

- Implements stacked bar chart for age group comparison
- Adds filter for selecting comparison metrics
- Updates documentation

Closes #123

Pull Request Process

1. Update your branch with the latest changes from develop

   git checkout develop
   git pull upstream develop
   git checkout your-branch-name
   git rebase develop
   

2. Push your changes to your fork

   git push origin your-branch-name
   

3. Create a pull request

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • Select dlangkip/epidash as the base repository and develop as the base branch
   • Select your fork as the head repository and your branch as the compare branch
   • Provide a clear title and description for your pull request
   • Reference any related issues

4. Wait for review

   • Maintainers will review your PR
   • Address any feedback or requested changes
   • Once approved, your PR will be merged

5. After merge

   • Delete your branch if no longer needed
   • Update any related documentation if necessary
   • Celebrate your contribution!

Coding Standards

HTML

• Use HTML5 semantic elements where appropriate
• Ensure proper indentation (2 spaces)
• Include appropriate ARIA attributes for accessibility
• Keep nested elements to a reasonable depth
• Use meaningful ID and class names

CSS

• Follow BEM (Block, Element, Modifier) naming convention
• Use CSS variables for colors, spacing, and other repeated values
• Write media queries for responsive design
• Keep selectors simple and avoid deep nesting
• Comment on complex or non-obvious styles

JavaScript

• Follow ES6+ conventions where possible
• Use camelCase for variables and functions
• Use PascalCase for constructor functions and classes
• Add JSDoc comments for functions
• Keep functions small and focused on a single task
• Use descriptive variable and function names
• Avoid global variables
• Handle errors appropriately

PHP

• Follow PSR-12 coding standards
• Use meaningful variable and function names
• Include appropriate error handling
• Validate and sanitize all inputs
• Add PHPDoc comments for functions and classes
• Keep functions short and focused

Testing Guidelines

While EpiDash currently doesn't have automated tests, contributions should include manual testing:

• Test your changes in multiple browsers (Chrome, Firefox, Safari, Edge)
• Test responsive behavior at different screen sizes
• Verify that existing functionality still works
• Check for console errors or warnings
• Test with both mock data and database data (if applicable)

When adding automated tests in the future, consider:

• Unit tests for individual functions
• Integration tests for component interactions
• End-to-end tests for complete user flows
• Accessibility tests for WCAG compliance

Documentation

Good documentation is essential for maintaining and extending EpiDash:

Code Documentation

• Add inline comments for complex logic
• Use JSDoc or PHPDoc for functions and classes
• Update README.md when adding new features
• Document any non-obvious behavior or edge cases

Wiki Documentation

When updating features, remember to update the wiki:

• User Guide for end-user features
• Technical Documentation for developer information
• API Reference for API changes
• Architecture Overview for structural changes
• Development Roadmap for new planned features

Community

EpiDash is currently a showcase project, but we welcome community involvement:

• Be respectful and constructive in all communications
• Help answer questions from other contributors
• Share your experience with the project
• Provide feedback on proposed changes
• Thank others for their contributions

Questions?

If you have any questions about contributing that aren't covered here, please:

• Open an issue on GitHub
• Contact the project maintainer directly

Thank you for contributing to EpiDash!