CONTRIBUTING.md

Contributing to DataCoreX

Thank you for your interest in contributing to DataCoreX! We welcome contributions from the community and appreciate your help in making this project better.

Code of Conduct

By participating in this project, you are expected to uphold our Code of Conduct:

• Be respectful: Treat everyone with respect and kindness
• Be collaborative: Work together towards common goals
• Be inclusive: Welcome newcomers and different perspectives
• Be constructive: Provide helpful feedback and suggestions

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Java 17 or higher
• Node.js 16+ and npm
• Maven 3.6+
• Git

Setting up the Development Environment

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/DataCoreX.git
   cd DataCoreX

3. Add the original repository as an upstream remote:

   git remote add upstream https://github.com/ORIGINAL_OWNER/DataCoreX.git

4. Set up the backend:

   cd datacorex-backend
   mvn clean install

5. Set up the frontend:

   cd datacorex-frontend
   npm install

How to Contribute

Reporting Issues

Before creating an issue, please:

1. Search existing issues to avoid duplicates
2. Use the issue template if available
3. Provide detailed information:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details (OS, Java version, browser, etc.)
   • Screenshots or logs if applicable

Suggesting Features

We welcome feature suggestions! Please:

1. Check if the feature already exists or is planned
2. Create a detailed feature request including:
   • Problem the feature would solve
   • Proposed solution
   • Alternative solutions considered
   • Impact on existing functionality

Contributing Code

Before You Start

1. Create or comment on an issue to discuss your proposed changes
2. Wait for approval from maintainers for significant changes
3. Check the project roadmap to ensure alignment

Development Workflow

1. Create a feature branch from the main branch:

   git checkout main
   git pull upstream main
   git checkout -b feature/your-feature-name

2. Make your changes following our coding standards

3. Test your changes:

   # Backend tests
   cd datacorex-backend
   mvn test
   
   # Frontend tests
   cd datacorex-frontend
   npm test

4. Commit your changes with a clear message:

   git add .
   git commit -m "feat: add new feature description"

5. Push to your fork:

   git push origin feature/your-feature-name

6. Create a Pull Request with:

   • Clear title and description
   • Reference to related issues
   • Screenshots if UI changes
   • Testing instructions

Commit Message Guidelines

We follow the Conventional Commits specification:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat: add user authentication with JWT
fix: resolve file upload issue on large files
docs: update API documentation for storage endpoints

Coding Standards

Java/Spring Boot Backend

• Code Style: Follow Google Java Style Guide
• Naming: Use descriptive names for classes, methods, and variables
• Documentation: Add Javadoc for public methods and classes
• Testing: Write unit tests for new functionality
• Logging: Use appropriate log levels (DEBUG, INFO, WARN, ERROR)

Example:

/**
 * Service for managing user authentication and authorization.
 */
@Service
public class AuthenticationService {

    private static final Logger logger = LoggerFactory.getLogger(AuthenticationService.class);

    /**
     * Authenticates a user with username and password.
     *
     * @param username the username
     * @param password the password
     * @return authentication result
     * @throws AuthenticationException if authentication fails
     */
    public AuthenticationResult authenticate(String username, String password) {
        // Implementation
    }
}

React/JavaScript Frontend

• Code Style: Use ESLint and Prettier configurations
• Components: Use functional components with hooks
• Naming: Use PascalCase for components, camelCase for functions and variables
• Testing: Write tests for components and utilities
• Documentation: Add JSDoc for complex functions

Example:

/**
 * Component for displaying user profile information.
 *
 * @param {Object} props - Component props
 * @param {Object} props.user - User object
 * @param {Function} props.onEdit - Edit callback function
 */
const UserProfile = ({ user, onEdit }) => {
  const [loading, setLoading] = useState(false)

  // Component implementation
}

Database Changes

• Migrations: Create Flyway migration scripts for schema changes
• Versioning: Use sequential version numbers (V1__Initial_setup.sql)
• Rollback: Consider rollback strategies for breaking changes
• Documentation: Document schema changes in commit messages

Testing Guidelines

Backend Testing

• Unit Tests: Test individual methods and classes
• Integration Tests: Test API endpoints and database interactions
• Test Coverage: Aim for at least 80% code coverage
• Test Data: Use test-specific data, don't rely on production data

Frontend Testing

• Component Tests: Test individual React components
• Integration Tests: Test user workflows and API interactions
• Accessibility Tests: Ensure components are accessible
• Visual Tests: Include visual regression tests for UI changes

Test Naming

Use descriptive test names that explain the scenario:

@Test
void shouldReturnUserProfileWhenValidTokenProvided() {
    // Test implementation
}

@Test
void shouldThrowExceptionWhenInvalidCredentialsProvided() {
    // Test implementation
}

Documentation

Code Documentation

• Javadoc: Document all public APIs
• README: Update README.md for significant changes
• API Docs: Update OpenAPI/Swagger documentation
• Comments: Explain complex logic, not obvious code

User Documentation

• Setup Guides: Update installation and setup instructions
• API Documentation: Keep API docs current with code changes
• Feature Documentation: Document new features and usage
• Troubleshooting: Add common issues and solutions

Review Process

Pull Request Requirements

Before submitting a PR, ensure:

• Code follows project coding standards
• All tests pass
• Documentation is updated
• No merge conflicts
• PR description explains the changes
• Related issues are referenced

Review Criteria

We review PRs based on:

• Functionality: Does the code work as intended?
• Code Quality: Is the code readable, maintainable, and well-structured?
• Testing: Are there adequate tests for the changes?
• Documentation: Is the documentation updated and clear?
• Performance: Does the change impact system performance?
• Security: Are there any security implications?

Review Timeline

• Initial Review: Within 2-3 business days
• Follow-up: Responses to feedback within 1-2 business days
• Approval: Final approval after all feedback is addressed

Release Process

Version Numbering

We use Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Release Checklist

• All tests pass
• Documentation updated
• CHANGELOG.md updated
• Version numbers updated
• Security review completed
• Performance testing completed

Getting Help

If you need help or have questions:

• Documentation: Check the README and wiki
• Issues: Search existing issues or create a new one
• Discussions: Use GitHub Discussions for general questions
• Contact: Reach out to maintainers directly for urgent matters

Recognition

We appreciate all contributions and recognize contributors in:

• CONTRIBUTORS.md: List of all contributors
• Release Notes: Special mentions for significant contributions
• GitHub: Contributor statistics and badges

Thank you for contributing to DataCoreX! 🚀