How to Contribute
We welcome contributions to the Veterinaria ALFA Inventory System! Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated.Getting Started
Set Up Development Environment
Ensure you have the prerequisites installed:
- Java Development Kit (JDK) 21
- Apache Maven 3.6+
- Git
Development Workflow
1. Making Changes
Follow the project structure and coding conventions:2. Build and Test
Before committing, ensure your code builds and tests pass:Always run the full build before submitting a pull request to ensure you haven’t introduced any breaking changes.
3. Commit Your Changes
Write clear, descriptive commit messages:Commit Message Convention
Use the following prefixes:- Add: New features or functionality
- Fix: Bug fixes
- Update: Improvements to existing features
- Refactor: Code restructuring without functionality changes
- Docs: Documentation changes
- Test: Adding or updating tests
- Chore: Maintenance tasks
4. Push to Your Fork
5. Create a Pull Request
Open a pull request from your fork to the main repository:Provide a Clear Title
Use the same convention as commit messages:
- “Add: Inventory export to CSV functionality”
- “Fix: Database connection timeout issue”
Write a Detailed Description
Include:
- What changes were made
- Why the changes were necessary
- How to test the changes
- Screenshots (for UI changes)
- Related issues (if applicable)
Code Style Guidelines
Java Coding Standards
Code Formatting
- Indentation: Use 4 spaces (no tabs)
- Line Length: Maximum 120 characters
- Braces: Opening brace on same line, closing brace on new line
- Spacing: One blank line between methods
Documentation
Add JavaDoc comments for public classes and methods:Testing Guidelines
Writing Tests
The project uses JUnit Jupiter (5.10.0) for testing. Place test files in:Test Structure
Running Tests
Project-Specific Guidelines
Database Operations
When working with the SQLite database:- Always use prepared statements to prevent SQL injection
- Close connections and statements properly
- Handle exceptions appropriately
- Use the DAO pattern for database operations
UI Components
When modifying or adding view components:- Follow the existing MVC pattern
- Keep view logic separate from business logic
- Use JCalendar components for date selection
- Ensure proper event handling and listeners
- Test UI changes manually before submitting
Dependencies
Before adding new dependencies:- Check if existing dependencies can fulfill the requirement
- Verify the dependency is actively maintained
- Check for security vulnerabilities
- Update
pom.xmlwith appropriate version and scope
Pull Request Review Process
Once you submit a pull request:Code Review
Maintainers will review your code and may request changes.Be responsive to feedback and make requested changes promptly.
What Reviewers Look For
- Code quality and adherence to style guidelines
- Proper error handling
- Test coverage (if applicable)
- Documentation updates
- No breaking changes without discussion
- Performance implications
Getting Help
If you need help or have questions:- Check the documentation first
- Look through existing issues and pull requests
- Open a new issue with your question
- Tag your issue appropriately (question, help wanted, etc.)
When asking for help, provide as much context as possible: what you’re trying to achieve, what you’ve tried, error messages, and relevant code snippets.
Types of Contributions
Bug Fixes
- Report bugs through issues
- Include steps to reproduce
- Provide error messages and logs
- Submit a fix with tests
New Features
- Discuss major features in an issue first
- Get consensus before starting work
- Include documentation updates
- Add tests for new functionality
Documentation
- Fix typos and improve clarity
- Add examples and tutorials
- Update outdated information
- Translate documentation (if applicable)
Code Refactoring
- Discuss refactoring plans in an issue
- Ensure tests pass after refactoring
- Maintain backward compatibility
- Document any API changes