# Contributing to Metis Admin Template

Thank you for your interest in contributing to the Metis Admin Template! This document provides guidelines and instructions for contributing.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Making Changes](#making-changes)
- [Submitting Changes](#submitting-changes)
- [Style Guidelines](#style-guidelines)
- [Reporting Issues](#reporting-issues)

---

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. Please:

- Be respectful and considerate in all interactions
- Welcome newcomers and help them get started
- Focus on constructive feedback
- Accept differing viewpoints gracefully

---

## Getting Started

### Prerequisites

- **Node.js 18+** - [Download](https://nodejs.org/)
- **Git** - [Download](https://git-scm.com/)
- **Code editor** - We recommend [VS Code](https://code.visualstudio.com/)

### Fork and Clone

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

```bash
git clone https://github.com/YOUR_USERNAME/Bootstrap-Admin-Template-3.git
cd Bootstrap-Admin-Template-3
```

3. **Add upstream remote**:

```bash
git remote add upstream https://github.com/puikinsh/Bootstrap-Admin-Template-3.git
```

---

## Development Setup

### Install Dependencies

```bash
npm install
```

### Start Development Server

```bash
npm run dev
```

The development server will start at `http://localhost:3000` with hot module replacement enabled.

### Useful Commands

```bash
npm run dev          # Start dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Check for linting errors
npm run lint:fix     # Auto-fix linting errors
npm run format       # Format code with Prettier
npm run format:check # Check code formatting
npm run check        # Run lint + format check
npm run audit        # Fail on high/critical advisories
npm run test:build   # Build, then smoke-test all 21 pages in a headless browser
npm run verify       # lint + audit + test:build — run before opening a PR
```

The smoke test loads every built page in headless Chromium and fails on uncaught
exceptions, console errors, failed or external requests, chart pages that render
no charts, and element pages that render no highlighted code.

Playwright is deliberately **not** a dependency (it would add a large install for
everyone who just wants to build the template). Provide it yourself:

```bash
npx playwright install chromium
PLAYWRIGHT_PATH=playwright npm run test:build
```

---

## Making Changes

### Branch Naming

Create a descriptive branch name:

```bash
# Features
git checkout -b feature/add-dark-mode-toggle

# Bug fixes
git checkout -b fix/sidebar-collapse-issue

# Documentation
git checkout -b docs/update-readme

# Refactoring
git checkout -b refactor/improve-chart-performance
```

### Commit Messages

Follow conventional commit format:

```
type(scope): description

[optional body]

[optional footer]
```

**Types:**
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation changes
- `style` - Code style changes (formatting, etc.)
- `refactor` - Code refactoring
- `perf` - Performance improvements
- `test` - Adding or updating tests
- `chore` - Maintenance tasks

**Examples:**

```bash
feat(sidebar): add collapsible menu sections

fix(charts): resolve memory leak on page navigation

docs(readme): update installation instructions

style(forms): improve input field spacing
```

### Keep Commits Atomic

- Each commit should represent a single logical change
- Avoid mixing unrelated changes in one commit
- Keep commits small and focused

---

## Submitting Changes

### Before Submitting

1. **Sync with upstream**:

```bash
git fetch upstream
git rebase upstream/main
```

2. **Run checks**:

```bash
npm run check
npm run build
```

3. **Test your changes**:
   - Test in multiple browsers (Chrome, Firefox, Safari)
   - Test responsive layouts
   - Test dark/light mode

### Pull Request Process

1. **Push your branch**:

```bash
git push origin feature/your-feature-name
```

2. **Create Pull Request** on GitHub

3. **Fill out the PR template**:
   - Describe what changes you made
   - Reference any related issues
   - Include screenshots for UI changes

4. **Address review feedback** if requested

### PR Title Format

```
type(scope): description
```

Examples:
- `feat(dashboard): add real-time notifications`
- `fix(forms): resolve validation error display`
- `docs: add deployment guide`

---

## Style Guidelines

### JavaScript

- Use ES6+ features (arrow functions, destructuring, etc.)
- Use meaningful variable and function names
- Keep functions small and focused
- Add comments for complex logic

```javascript
// Good
const calculateTotal = (items) => {
  return items.reduce((sum, item) => sum + item.price, 0);
};

// Avoid
const calc = (i) => i.reduce((s, x) => s + x.p, 0);
```

### SCSS

- Follow BEM naming convention
- Use variables for colors, spacing, etc.
- Keep selectors specific but not overly nested

```scss
// Good
.card {
  &__header {
    padding: $spacer;
  }

  &__title {
    font-weight: $font-weight-semibold;
  }

  &--primary {
    border-color: $primary;
  }
}

// Avoid deep nesting
.card {
  .header {
    .title {
      .text {
        // Too deep!
      }
    }
  }
}
```

### HTML

- Use semantic HTML elements
- Include ARIA labels for accessibility
- Keep indentation consistent (2 spaces)

```html
<!-- Good -->
<nav aria-label="Main navigation">
  <ul class="nav-list">
    <li class="nav-item">
      <a href="#" class="nav-link">Home</a>
    </li>
  </ul>
</nav>

<!-- Avoid -->
<div onclick="navigate()">
  <div>
    <div>Home</div>
  </div>
</div>
```

### Alpine.js Components

- Keep components focused and reusable
- Use descriptive data property names
- Document complex logic

```javascript
Alpine.data('searchComponent', () => ({
  query: '',
  results: [],
  isLoading: false,

  async search() {
    if (!this.query.trim()) return;

    this.isLoading = true;
    try {
      this.results = await this.fetchResults(this.query);
    } finally {
      this.isLoading = false;
    }
  },

  async fetchResults(query) {
    // Implementation
  }
}));
```

---

## Reporting Issues

### Before Reporting

1. Search existing issues to avoid duplicates
2. Try the latest version to see if it's already fixed
3. Gather relevant information

### Issue Template

**Bug Report:**

```markdown
## Description
A clear description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- Browser: Chrome 120
- OS: macOS 14
- Node.js: 20.10.0

## Screenshots
If applicable, add screenshots.
```

**Feature Request:**

```markdown
## Description
A clear description of the feature.

## Use Case
Why this feature would be useful.

## Proposed Solution
How you think it could be implemented.

## Alternatives Considered
Other approaches you've considered.
```

---

## Questions?

If you have questions about contributing:

1. Check existing [GitHub Discussions](https://github.com/puikinsh/Bootstrap-Admin-Template-3/discussions)
2. Open a new discussion for general questions
3. Open an issue for bugs or feature requests

---

Thank you for contributing to Metis Admin Template!