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

4. Start the Development Server

php artisan serve

📋 Essential Guidelines

Before contributing, please review our development guidelines:

📖 Coding Guidelines

🧪 Testing Guidelines

📝 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: July 09, 2025