CONTRIBUTING.md

Contributing to Metarang Microservice Admin Panel

First off, thank you for considering contributing to Metarang Admin Panel! It's people like you that make Metarang better. 🎉

📋 Table of Contents

• Code of Conduct
• Getting Started
• How Can I Contribute?
  • Reporting Bugs
  • Suggesting Enhancements
  • Pull Requests
• Development Workflow
• Coding Standards
  • PHP/Laravel Standards
  • Vue.js/JavaScript Standards
  • CSS/Tailwind Standards
• Commit Guidelines
• Testing Requirements
• Documentation

Code of Conduct

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

• PHP 8.2+
• Node.js 18+
• Composer
• NPM or Yarn
• MySQL/PostgreSQL

Setup Development Environment

# Fork the repository
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/microservice-admin-panel.git
cd microservice-admin-panel

# Install dependencies
composer install
npm install

# Setup environment
cp .env.example .env
php artisan key:generate

# Setup database
php artisan migrate --seed

# Start development servers
php artisan serve
npm run dev

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

Bug Report Template:

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Environment (please complete the following information):**
- OS: [e.g., Ubuntu 22.04]
- PHP Version: [e.g., 8.2.5]
- Node Version: [e.g., 18.15.0]
- Browser: [e.g., chrome, safari]
- Version: [e.g., 22]

**Additional context**
Add any other context about the problem here.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

• Use a clear and descriptive title
• Provide a step-by-step description of the suggested enhancement
• Provide specific examples to demonstrate the steps
• Describe the current behavior and explain which behavior you expected to see instead
• Explain why this enhancement would be useful

Pull Requests

Step-by-Step Guide

1. Fork the repository and create your branch from main
2. Update the documentation if you're changing functionality
3. Add tests for any new code
4. Ensure the test suite passes
5. Make sure your code lints (PSR-12 for PHP, ESLint for JS/Vue)
6. Issue that pull request 🎉

Pull Request Template

## Description
Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.

Fixes # (issue)

## Type of change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
Please describe the tests that you ran to verify your changes.

- [ ] Unit Tests
- [ ] Feature Tests
- [ ] Manual Testing

## Checklist:
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Development Workflow

Branch Naming Convention

Use meaningful branch names:

• feature/description - for new features
• bugfix/description - for bug fixes
• hotfix/description - for critical fixes
• docs/description - for documentation
• refactor/description - for code refactoring
• test/description - for adding tests

Examples:

• feature/user-authentication
• bugfix/fix-file-upload
• docs/update-readme

Development Process

1. Always create an issue first - Discuss the change before implementing
2. Assign yourself to the issue - Let others know you're working on it
3. Create a branch from main with the naming convention above
4. Make your changes following the coding standards
5. Write/update tests for your changes
6. Run tests locally to ensure everything passes
7. Push your branch and create a Pull Request
8. Request review from maintainers

Coding Standards

PHP/Laravel Standards

We follow PSR-1, PSR-12, and Laravel best practices:

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Requests\UserRequest;
use Illuminate\Http\JsonResponse;

class UserController extends Controller
{
    /**
     * Display a listing of users.
     *
     * @return JsonResponse
     */
    public function index(): JsonResponse
    {
        $users = User::paginate(15);
        
        return response()->json($users);
    }
    
    /**
     * Store a newly created user.
     *
     * @param UserRequest $request
     * @return JsonResponse
     */
    public function store(UserRequest $request): JsonResponse
    {
        $validated = $request->validated();
        $user = User::create($validated);
        
        return response()->json($user, 201);
    }
}

Key Rules:

• Use type hints and return types
• Use Laravel's built-in validation (Form Requests)
• Follow Laravel naming conventions (snake_case for variables, camelCase for methods)
• Use dependency injection where possible
• Keep controllers thin - use Services/Repositories
• Add PHPDoc blocks for complex methods

Vue.js/JavaScript Standards

We use Vue 3 Composition API with TypeScript:

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useUserStore } from '@/stores/user'

interface Props {
  userId: number
  isActive?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  isActive: false
})

const emit = defineEmits<{
  (e: 'update', value: User): void
  (e: 'delete', id: number): void
}>()

const userStore = useUserStore()
const loading = ref(false)

onMounted(async () => {
  await fetchUserData()
})

const fetchUserData = async () => {
  loading.value = true
  try {
    await userStore.fetchUser(props.userId)
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <div class="p-4" :class="{ 'bg-gray-100': isActive }">
    <h2 class="text-xl font-bold">User Profile</h2>
    <p v-if="loading" class="text-gray-500">Loading...</p>
    <slot name="content" />
  </div>
</template>

<style scoped>
/* Component-specific styles */
</style>

Key Rules:

• Use Composition API with <script setup>
• Use TypeScript for props, emits, and complex logic
• Prefer ref over reactive for simple values
• Use composables for reusable logic (e.g., useBreakpoint)
• Keep components focused and under 300 lines
• Use meaningful component names (PascalCase)

CSS/Tailwind Standards

• Use Tailwind CSS utility classes primarily
• Use <style scoped> for component-specific styles
• Avoid inline styles
• Follow BEM naming if writing custom CSS
• Maintain responsive design (mobile-first approach)

<template>
  <!-- Good: Mobile-first responsive design -->
  <div class="w-full md:w-1/2 lg:w-1/3 p-4">
    <button class="px-4 py-2 bg-blue-500 hover:bg-blue-600 rounded">
      Click me
    </button>
  </div>
</template>

<style scoped>
/* Only for complex animations or overrides */
.custom-animation {
  transition: all 0.3s ease;
}
</style>

Commit Guidelines

We follow Conventional Commits specification:

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

Type	Description	Example
feat	New feature	feat: add user profile page
fix	Bug fix	fix: resolve file upload issue
docs	Documentation	docs: update API documentation
style	Code style (formatting, missing semicolons, etc)	style: format code with prettier
refactor	Code refactoring	refactor: extract validation logic
test	Adding tests	test: add user model unit tests
chore	Maintenance tasks	chore: update composer dependencies
perf	Performance improvements	perf: optimize database queries

Examples

# Feature commit
git commit -m "feat(user): add email verification on registration"

# Bug fix commit  
git commit -m "fix(upload): fix FileInput loading state not resetting"

# Documentation commit
git commit -m "docs(readme): update installation instructions"

# Breaking change
git commit -m "feat(api)!: change authentication response format

BREAKING CHANGE: API now returns JWT token instead of session cookie"

Testing Requirements

PHP Unit Tests

# Run all tests
php artisan test

# Run specific test suite
php artisan test --testsuite=Feature

# Run with coverage
php artisan test --coverage

Requirements:

• Write tests for all new features
• Maintain at least 80% code coverage
• Test both success and failure scenarios

Example Test:

<?php

namespace Tests\Feature;

use Tests\TestCase;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

class UserControllerTest extends TestCase
{
    use RefreshDatabase;
    
    /** @test */
    public function it_can_create_a_user()
    {
        $userData = [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'password' => 'password123'
        ];
        
        $response = $this->postJson('/api/users', $userData);
        
        $response->assertStatus(201)
                 ->assertJsonPath('name', 'John Doe');
                 
        $this->assertDatabaseHas('users', ['email' => 'john@example.com']);
    }
}

Vue Component Tests

# Run Vue tests
npm run test

# Run with watch mode
npm run test:watch

Example Component Test:

import { mount } from '@vue/test-utils'
import FileInput from '@/components/FileInput.vue'

describe('FileInput.vue', () => {
  it('emits file when uploaded', async () => {
    const wrapper = mount(FileInput)
    const file = new File(['content'], 'test.txt')
    
    await wrapper.find('input').trigger('change', { files: [file] })
    
    expect(wrapper.emitted()).toHaveProperty('file-uploaded')
  })
})

Documentation

In-code Documentation

• Use PHPDoc for PHP classes and methods
• Use JSDoc for JavaScript/Vue functions
• Comment complex logic, not obvious code

/**
 * Process user upload with validation and optimization.
 *
 * @param UploadedFile $file The uploaded file instance
 * @param array $options Processing options (resize, compress)
 * @return ProcessedFile|null Returns processed file or null on failure
 * @throws \InvalidArgumentException When file type is not supported
 */

README and Wiki

• Update README.md when adding features
• Document API endpoints in wiki
• Keep installation instructions up-to-date

Review Process

Pull requests require at least one approval from a maintainer. The review checks for:

• Code quality and standards compliance
• Test coverage
• Documentation updates
• No breaking changes without discussion
• Performance implications

Recognition

Contributors will be:

• Added to the README contributors list
• Mentioned in release notes
• Featured on our contributors wall (coming soon)

---

Questions?

• GitHub Issues: For bug reports and feature requests
• Discord: Join our Discord server for real-time chat
• Email: contributors@metarang.com

Thank you for contributing to Metarang! 🚀

Happy Coding! 💻

**END OF CONTRIBUTING GUIDE**