Contributing to Martor

We welcome contributions to Martor! This guide will help you get started with contributing to the project.

Ways to Contribute

There are many ways you can contribute to Martor:

Report bugs - Help us identify and fix issues
Suggest features - Propose new functionality or improvements
- Write code - Implement bug fixes or new features
Improve documentation - Help make our docs better
Test the project - Help ensure quality across different environments
Share your experience - Write blog posts, tutorials, or give talks

Getting Started

Setting Up Development Environment

Fork the repository on GitHub
Clone your fork:

git clone https://github.com/YOUR-USERNAME/django-markdown-editor.git
cd django-markdown-editor

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install development dependencies:

pip install -e .[dev]

Install the demo project dependencies:

cd martor_demo
pip install -r requirements.txt

Run migrations:

python manage.py migrate

Create a superuser:

python manage.py createsuperuser

Run the development server:

python manage.py runserver

Development Workflow

Creating a Feature Branch

Always create a new branch for your changes:

git checkout -b feature/your-feature-name
# or
git checkout -b bugfix/issue-number

Making Changes

Write tests for your changes (see Testing section below)
Implement your changes
Update documentation if needed
Run the test suite to ensure nothing is broken
Test manually using the demo project

Committing Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add user mention autocomplete feature

- Implement real-time user search
- Add keyboard navigation support
- Update documentation with configuration options

Closes #123"

Submitting a Pull Request

Push your branch to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub
Fill out the PR template with all required information
Wait for review and address any feedback

Coding Standards

Code Style

We follow Django’s coding style and PEP 8:

Use 4 spaces for indentation
Line length should not exceed 120 characters
Use descriptive variable and function names
Follow Django naming conventions

Format your code using Black:

black .

Sort imports using isort:

isort .

Check code quality using flake8:

flake8 .

Python and Django Compatibility

Martor supports:

Python: 3.9+
Django: 3.2+

Ensure your code works with all supported versions.

JavaScript and CSS

For frontend code:

Use modern JavaScript (ES6+) with appropriate polyfills
Follow consistent indentation and naming
Comment complex logic
Test across different browsers

Testing

Running Tests

Run the full test suite:

python runtests.py

Run specific tests:

python runtests.py martor.tests.test_models

Run tests with coverage:

coverage run runtests.py
coverage report

Writing Tests

Test Organization:

martor/tests/
├── __init__.py
├── test_models.py      # Model tests
├── test_fields.py      # Field tests
├── test_widgets.py     # Widget tests
├── test_views.py       # View tests
├── test_utils.py       # Utility tests
└── test_templates.py   # Template tests

Example Test:

from django.test import TestCase
from martor.models import MartorField
from martor.fields import MartorFormField

class MartorFieldTest(TestCase):
    def test_field_creation(self):
        """Test that MartorField can be created with default settings."""
        field = MartorField()
        self.assertIsInstance(field, MartorField)

    def test_field_with_custom_settings(self):
        """Test MartorField with custom parameters."""
        field = MartorField(
            verbose_name="Custom Content",
            help_text="Custom help text",
            blank=True
        )
        self.assertEqual(field.verbose_name, "Custom Content")
        self.assertEqual(field.help_text, "Custom help text")
        self.assertTrue(field.blank)

Testing Guidelines:

Write tests for all new functionality
Ensure tests are isolated and repeatable
Use descriptive test method names
Test both success and failure cases
Mock external dependencies (like imgur API)

Documentation

Documentation Structure

Our documentation uses Sphinx and is organized as follows:

docs/
├── index.rst           # Main documentation page
├── installation.rst    # Installation guide
├── quickstart.rst      # Quick start guide
├── settings.rst        # Configuration reference
├── usage/             # Usage guides
├── api/               # API reference
├── examples/          # Examples and tutorials
└── ...

Writing Documentation

Documentation Guidelines:

Use clear, concise language
Provide working code examples
Include both basic and advanced usage
Update relevant sections when adding features
Use proper reStructuredText formatting

Building Documentation:

cd docs
pip install -r requirements.txt
sphinx-build -b html . _build/html

Viewing Documentation:

# Open _build/html/index.html in your browser

Common Contribution Scenarios

Adding a New Feature

Create an issue to discuss the feature first
Design the API - think about how users will interact with it
Write tests for the expected behavior
Implement the feature
Update documentation
Test thoroughly

Fixing a Bug

Create a test that reproduces the bug
Fix the issue
Ensure the test passes
Update documentation if the bug was due to unclear docs

Improving Documentation

Identify areas that need improvement
Write clear explanations with examples
Test the examples to ensure they work
Update the index and navigation if needed

Pull Request Guidelines

PR Requirements

Before submitting a pull request, ensure:

✅ Tests pass - All existing tests continue to pass
✅ New tests added - For new functionality or bug fixes
✅ Documentation updated - If the change affects user-facing functionality
✅ Code style - Follows project coding standards
✅ No breaking changes - Unless discussed and approved

PR Description Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Related Issue
Closes #(issue number)

## Testing
- [ ] Tests added/updated
- [ ] Manual testing completed
- [ ] Works with supported Django versions

## Screenshots (if applicable)
Add screenshots to help explain your changes.

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests pass locally

Review Process

Automated checks run on your PR
Code review by maintainers
Feedback and requested changes
Approval and merge

Be patient during the review process and responsive to feedback.

Community Guidelines

Code of Conduct

We expect all contributors to follow our Code of Conduct:

Be respectful and inclusive
Be constructive in feedback and discussions
Help others learn and grow
Assume good intentions

Communication

GitHub Issues for bug reports and feature requests
Pull Requests for code contributions
Discussions for general questions and ideas

Getting Help

If you need help with contributing:

Read the documentation thoroughly
Search existing issues for similar problems
Ask questions in GitHub Discussions
Tag maintainers if you need specific guidance

Recognition

We appreciate all contributions to Martor! Contributors are recognized in:

GitHub contributors list
Release notes for significant contributions
Documentation credits

Thank you for contributing to Martor and helping make it better for everyone!