Contributing Guidelines

We welcome contributions to the Inventory Management API! This document provides guidelines for contributing to this RESTful API project built with PHP 8.2+ and Laravel 12.

🚀 Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/inventory-app.git
cd inventory-app

# Add the original repository as upstream
git remote add upstream https://github.com/metanull/inventory-app.git

2. Retrieve Dependencies

# Install PHP dependencies
composer install

# Install Node.js dependencies (for frontend assets and code quality tools)
npm install

3. Set Up Development Environment

Using our composer scripts

See composer.json for a list of ci/cd scripts

composer ci-reset

Or using artisan

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Generate application key
php artisan key:generate

# Set up database and run migrations
php artisan migrate --seed

# Build frontend assets
npm run build

[#### Using Composer Scripts (Recommended)]

To quickly set up your environment, use our custom composer scripts. These automate database setup, migrations, and seeding for both development and testing:

composer ci-reset

Manual Setup with Artisan

If you need more control or want to customize the seeding process, use Laravel Artisan commands:

# Copy environment file and configure your settings
cp .env.example .env
# Edit .env with your database and app configuration

# Generate application key
php artisan key:generate

# Run migrations and seed the database
php artisan migrate --seed

Seeding Optimization

The application supports multiple seeding strategies to optimize development and testing:

When to use which seeding version:

Build Frontend Assets

npm run build

4. Start the Development Server

php artisan serve

📋 Essential Guidelines

Before contributing, please review our development guidelines:

📖 Coding Guidelines

🧪 Testing Guidelines

🏷️ Automated Versioning

This project uses automated semantic versioning based on GitHub pull request labels. Understanding this system is crucial for contributors.

Version Bump Labels

Every pull request MUST include one of these labels:

Label Version Bump Example When to Use
bugfix Patch 1.0.0 → 1.0.1 Bug fixes, documentation updates, code cleanup
feature Minor 1.0.0 → 1.1.0 New features, enhancements, non-breaking additions
breaking-change Major 1.0.0 → 2.0.0 Breaking API changes, removed functionality

How the Automation Works

  1. Create PR → CI runs all tests and validations
  2. Tests pass → Version bump job analyzes PR labels
  3. Version updated → New version automatically committed to your PR branch
  4. PR reviewed & merged → Deployment uses the correct version
  5. App updated → New version visible in application footer

Label Guidelines

🟢 Use bugfix for:

🟡 Use feature for:

🔴 Use breaking-change for:

Example Workflows

# Bug fix workflow
git checkout -b fix/login-validation-error
# Make your changes
# Create PR with 'bugfix' label → Results in patch bump

# New feature workflow
git checkout -b feature/user-dashboard
# Make your changes
# Create PR with 'feature' label → Results in minor bump

# Breaking change workflow
git checkout -b breaking/redesign-api-endpoints
# Make your changes
# Create PR with 'breaking-change' label → Results in major bump

Important Notes

💡 Pro Tip: Add labels when creating the PR or immediately after. The version bump happens after CI passes, so you’ll see the version commit appear in your PR before it’s merged!

📝 Contribution Process

1. Create a Feature Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

2. Make Your Changes

3. Commit Your Changes

We follow Conventional Commits:

# Examples of good commit messages
git commit -m "feat: add new API endpoint for tag management"
git commit -m "fix: resolve validation issue in item controller"
git commit -m "docs: update API documentation for new endpoints"
git commit -m "test: add unit tests for markdown service"

4. Push and Create Pull Request

# Push your branch
git push origin feature/your-feature-name

Option A: Using GitHub Web Interface

  1. Navigate to your fork on GitHub
  2. Click “Compare & pull request”
  3. Provide a clear title and description
  4. Reference any related issues
  5. Wait for code review
# Install GitHub CLI (if not already installed)
# Windows PowerShell: winget install GitHub.cli
# Or use chocolatey: choco install gh

# Authenticate (one-time setup)
gh auth login

# Create PR with auto-merge and squash
gh pr create --title "feat: add new API endpoint" --body "Description of changes" \
  --assignee @me \
  --label "enhancement" \
  --auto-merge \
  --squash

✅ Pre-Submission Checklist

Before submitting your PR, ensure you’ve followed our guidelines:

Code Quality

Testing

Documentation

Git

🔍 Code Review Process

What We Look For

  1. Code Quality
    • Follows our coding guidelines
    • Proper error handling and validation
    • Clean, readable PHP code structure
    • Laravel best practices compliance
  2. Testing
    • Meets our testing requirements
    • Unit tests for models and services
    • Feature tests for API endpoints
    • Edge cases covered
  3. Performance
    • Efficient database queries (avoid N+1 problems)
    • Proper use of Eloquent relationships
    • Appropriate caching where needed
    • Optimized API responses
  4. Security
    • Input validation and sanitization
    • Proper authentication and authorization
    • No SQL injection vulnerabilities
    • Secure file upload handling

🎯 Areas for Contribution

We especially welcome contributions in these areas:

📞 Getting Help

For technical questions about our development practices, please refer to our guidelines section.

🏆 Recognition

Contributors will be recognized in:

Thank you for contributing to the Inventory Management API! 🎉

Last updated: October 22, 2025