Contributing to Mage-OS
Mage-OS is built by contributors like you. Whether you write code, improve documentation, report bugs, or help others—every contribution matters.
Ways to Contribute
There are many ways to help, regardless of your experience level
Code
Fix bugs, add features, improve performance, or submit security patches to the core distribution.
Documentation
Improve guides, add tutorials, translate content, or clarify technical documentation.
Testing
Test new releases, report bugs, verify fixes, or help with quality assurance.
Community
Answer questions on Discord, help newcomers, share knowledge, or organize local meetups.
Code Contribution Workflow
Follow these steps to submit your first pull request
Step 1: Fork the Repository
Create your own fork of the Mage-OS repository on GitHub. This gives you a personal copy to work with.
Step 2: Set Up Development Environment
Clone your fork locally and set up a development environment with PHP, MySQL, Elasticsearch/OpenSearch, and required dependencies.
Step 3: Create a Feature Branch
Create a descriptive branch name (e.g., fix/cart-calculation-bug or feature/improved-caching).
Step 4: Make Your Changes
Write clean, tested code following Magento coding standards. Include unit or integration tests where appropriate.
Step 5: Submit a Pull Request
Push to your fork and open a PR against the main repository. Describe your changes clearly and link any related issues.
Quick Start Commands
Fork and clone the repository:
# Clone your fork
git clone https://github.com/YOUR-USERNAME/mageos-magento2.git
cd mageos-magento2
# Add upstream remote
git remote add upstream https://github.com/mage-os/mageos-magento2.gitCreate a feature branch:
# Update your local main branch
git checkout main
git pull upstream main
# Create and switch to a new branch
git checkout -b fix/your-descriptive-branch-nameSubmit your changes:
# Stage and commit your changes
git add .
git commit -m "Fix: Brief description of what was fixed"
# Push to your fork
git push origin fix/your-descriptive-branch-name
# Then open a PR on GitHubWhat Happens After You Submit
Transparent Review Process
Unlike some projects where PRs sit for months, Mage-OS prioritizes timely reviews. Most contributions receive initial feedback within a week.Automated CI Checks
Your PR triggers automated tests including unit tests, integration tests, static analysis, and coding standards checks.
Community Review
Maintainers and community members review your code for quality, compatibility, and adherence to best practices.
Feedback & Iteration
You may receive feedback requesting changes. This is normal—respond to comments and update your PR as needed.
Merge
Once approved, a maintainer merges your PR. Congratulations—you're now a Mage-OS contributor!
Types of Contributions We Value
All backwards-compatible improvements are welcome
Patches that fix existing issues without breaking changes
Optimizations to queries, caching, rendering, or resource usage
Better error messages, debugging tools, CLI improvements
Fixes for vulnerabilities (report first to security@mage-os.org)
Guides, tutorials, API docs, and inline code comments
Independent modules that extend functionality without modifying core
Coding Standards
All code contributions should follow Magento coding standards and best practices.
Do
- ✓ Follow PSR-12 coding style
- ✓ Write unit tests for new functionality
- ✓ Use dependency injection
- ✓ Type-hint against interfaces
- ✓ Keep PRs focused on one change
- ✓ Write clear commit messages
Don't
- ✗ Make breaking changes to public APIs
- ✗ Use the ObjectManager directly
- ✗ Skip automated tests
- ✗ Combine multiple unrelated changes
- ✗ Introduce new external dependencies without discussion
- ✗ Ignore CI failures
Resources
Everything you need to start contributing
