Thank you for your interest in contributing to the Metis Admin Template! This document provides guidelines and instructions for contributing.
- Code of Conduct
- Getting Started
- Development Setup
- Making Changes
- Submitting Changes
- Style Guidelines
- Reporting Issues
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
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/Bootstrap-Admin-Template-3.git
cd Bootstrap-Admin-Template-3- Add upstream remote:
git remote add upstream https://github.com/puikinsh/Bootstrap-Admin-Template-3.gitnpm installnpm run devThe development server will start at http://localhost:3000 with hot module replacement enabled.
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 30 pages + the auth interaction suite
npm run verify # lint + audit + test:build — run before opening a PRThe 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:
npx playwright install chromium
PLAYWRIGHT_PATH=playwright npm run test:buildCreate a descriptive branch name:
# 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-performanceFollow conventional commit format:
type(scope): description
[optional body]
[optional footer]
Types:
feat- New featurefix- Bug fixdocs- Documentation changesstyle- Code style changes (formatting, etc.)refactor- Code refactoringperf- Performance improvementstest- Adding or updating testschore- Maintenance tasks
Examples:
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- Each commit should represent a single logical change
- Avoid mixing unrelated changes in one commit
- Keep commits small and focused
- Sync with upstream:
git fetch upstream
git rebase upstream/main- Run checks:
npm run check
npm run build- Test your changes:
- Test in multiple browsers (Chrome, Firefox, Safari)
- Test responsive layouts
- Test dark/light mode
- Push your branch:
git push origin feature/your-feature-name-
Create Pull Request on GitHub
-
Fill out the PR template:
- Describe what changes you made
- Reference any related issues
- Include screenshots for UI changes
-
Address review feedback if requested
type(scope): description
Examples:
feat(dashboard): add real-time notificationsfix(forms): resolve validation error displaydocs: add deployment guide
- Use ES6+ features (arrow functions, destructuring, etc.)
- Use meaningful variable and function names
- Keep functions small and focused
- Add comments for complex logic
// 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);- Follow BEM naming convention
- Use variables for colors, spacing, etc.
- Keep selectors specific but not overly nested
// Good
.card {
&__header {
padding: $spacer;
}
&__title {
font-weight: $font-weight-semibold;
}
&--primary {
border-color: $primary;
}
}
// Avoid deep nesting
.card {
.header {
.title {
.text {
// Too deep!
}
}
}
}- Use semantic HTML elements
- Include ARIA labels for accessibility
- Keep indentation consistent (2 spaces)
<!-- 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>- Keep components focused and reusable
- Use descriptive data property names
- Document complex logic
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
}
}));- Search existing issues to avoid duplicates
- Try the latest version to see if it's already fixed
- Gather relevant information
Bug Report:
## 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:
## 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.If you have questions about contributing:
- Check existing GitHub Discussions
- Open a new discussion for general questions
- Open an issue for bugs or feature requests
Thank you for contributing to Metis Admin Template!