Skip to main content

​
Getting Started with Development

Django Admin Tabs uses Docker for development to ensure a consistent environment across all contributors.

​
Prerequisites

  • Git
  • Docker and Docker Compose
  • Make (optional, but recommended)

​
Setting Up the Development Environment

1

Clone the repository

git clone [email protected]:mehmetakyuz/django-admin-tabs.git
cd django-admin-tabs
2

Start the development environment

make dev
This command will:
  • Build the Docker container
  • Install all dependencies
  • Start the Django development server
  • Make the example project available at http://localhost:8000
3

Access the example project

Once the containers are running, visit http://localhost:8000/admin in your browser to see the example polls application with tabbed admin.
The make dev command uses Docker Compose to set up the entire environment. You don’t need to manually install Python, Django, or any dependencies.

​
Running the Example Project

The example project is a complete Django application demonstrating Django Admin Tabs with a Poll/Choice/Answer voting system.

​
Creating a Superuser

To log into the admin interface, you’ll need a superuser account: 
make superuser
Follow the prompts to create your admin account.

​
Example Project Structure

example/
├── __init__.py
├── settings.py       # Django settings with django_admin_tabs installed
├── urls.py           # URL configuration
├── wsgi.py          # WSGI application
└── polls/           # Example app
    ├── models.py    # Poll, Choice, and Answer models
    └── admin.py     # Tabbed admin configuration

​
Key Features to Explore

After creating a superuser and logging in, try these features:
  1. Create a new Poll with the question field
  2. Add Choices using the inline form on the Poll tab
  3. Switch to the Answers tab to see the nested changelist
  4. Add Answers and notice how the choice dropdown only shows choices from the current poll

​
Running Tests

The test suite ensures Django Admin Tabs works correctly across different Django versions.

​
Run All Tests

make test
This command runs the full test suite inside the Docker container: 
docker exec -it django-admin-tabs python manage.py test django_admin_tabs

​
Manual Testing

For manual testing and debugging:
1

Access the container shell

make shell
This opens a Django shell inside the running container.
2

Run specific tests

docker exec -it django-admin-tabs python manage.py test django_admin_tabs.tests.specific_test

​
Development Workflow

​
Making Changes

1

Create a branch

git checkout -b feature/my-new-feature
2

Make your changes

Edit files in the django_admin_tabs/ directory. The development server will automatically reload when you save files.
3

Run pre-commit hooks

make pre-commit
This runs code formatting and linting checks using the configured pre-commit hooks.
4

Test your changes

make test

​
Available Make Commands

CommandDescription
make devStart development containers with the example project
make testRun the test suite
make superuserCreate a Django superuser
make shellOpen a Django shell
make migrateRun database migrations
make makemigrationsCreate new migrations
make showmigrationsShow migration status
make pre-commitRun pre-commit hooks (formatting, linting)
make cleanpyRemove .pyc files and pycache
make cleanFull cleanup including virtual environment

​
Project Structure

django-admin-tabs/
├── django_admin_tabs/       # Main package
│   ├── __init__.py
│   ├── admin.py            # AdminTab, AdminChangeListTab, TabbedModelAdmin
│   ├── templates/          # Admin templates
│   └── static/             # CSS files
├── example/                # Example Django project
│   └── polls/             # Example polls app
├── docs/                   # Documentation
├── tests/                  # Test suite (if separate from main package)
├── Makefile               # Development commands
├── docker-compose.yml     # Docker configuration
├── Dockerfile             # Container definition
├── pyproject.toml         # Poetry dependencies and project metadata
├── setup.py               # Package setup
└── README.md              # Project README

​
Code Quality Tools

The project uses several tools to maintain code quality:

​
Pre-commit Hooks

Pre-commit hooks are configured in .pre-commit-config.yaml and run automatically before each commit. They include:
  • Ruff: Fast Python linter and formatter
  • Trailing whitespace removal
  • End-of-file fixes
  • YAML validation
Install pre-commit hooks locally: 
pre-commit install

​
Ruff Configuration

Ruff is used for both linting and formatting. Configuration is in pyproject.toml.

​
Contributing Guidelines

​
Before Submitting a PR

1

Ensure tests pass

make test
All tests must pass before submitting a pull request.
2

Run pre-commit hooks

make pre-commit
Code must pass all linting and formatting checks.
3

Test with the example project

Verify your changes work correctly with the example polls application:
make dev
# Visit http://localhost:8000/admin and test manually
4

Update documentation

If you’ve added features or changed behavior, update the relevant documentation.

​
Pull Request Process

  1. Fork the repository on GitHub
  2. Create a feature branch from main
  3. Make your changes with clear, descriptive commits
  4. Push to your fork and submit a pull request
  5. Respond to review feedback from maintainers
Write clear commit messages that explain what changed and why. Good commit messages help reviewers understand your changes and make the project history more useful.

​
Getting Help

If you run into issues during development:
  1. Check the GitHub Issues for similar problems
  2. Review the example project in the example/ directory
  3. Ask questions by opening a new issue with the “question” label

​
License

Django Admin Tabs is licensed under the Apache Software License. See the LICENSE file for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us