django / django/new-features

Enhance check command with structured output formats (--output-format)

Open
#78 8 comments 14 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
188
Forks
7
PR merge metrics
No merged PRs in 30d

Description

### Code of Conduct

- [x] I agree to follow Django's Code of Conduct

### Feature Description

The `check` command is an invaluable tool for ensuring project health. However, its current string-based output to `stderr` makes it difficult to parse and integrate into modern CI/CD pipelines and external tooling (e.g., Code Climate, GitHub Actions, GitLab CI). This proposal suggests adding a new optional argument, `--output-format`, to allow the `check` command to produce structured, machine-readable output. Additionally, it proposes a `--exit-zero` flag to prevent CI jobs from failing on warnings.

### Problem

Currently, when a `check` command is run, any violations are outputted as human-readable strings. For many CI/CD workflows, this requires complex and brittle string parsing to extract meaningful data about the issues found. This prevents Django check output from being directly ingested by code quality and security scanning tools, such as those that use the Code Climate or SARIF formats.

By providing structured output formats, developers can:

* Automatically upload code quality reports to GitLab, making them visible directly in merge requests.
* Annotate GitHub Actions pull requests with inline error messages.
* Ingest security vulnerability data into tools that support SARIF format.
* Programmatically process check results without relying on fragile string manipulation.

### Request or proposal

proposal

### Additional Details

_No response_

### Implementation Suggestions

1. **`--output-format` argument**
Add a new optional argument, `--output-format`, to the check command. The command will retain its existing default behavior for backwards compatibility.

**Suggested formats:**

* `full` (default): This option maintains the current behavior, outputting all messages (including `stdout` and `stderr`) as human-readable strings.
* `json`: This format would output a JSON array of objects. Each object would represent a single check violation and contain fields such as `code`, `message`, `level` (`INFO`, `WARNING`, `ERROR`), `hint` (if available), and `path` (if the check is tied to a specific file). This is a generic, machine-readable format that could be easily consumed by any third-party tool.
* `github`: This format would output messages formatted for GitHub Actions' workflow commands, specifically for creating file annotations. This would allow `check` violations to appear directly in the "Files changed" tab of a pull request.
* `gitlab`: This format would output a Code Climate-style JSON report, which is a standard format used by GitLab CI/CD's "Code Quality" feature.

Example of a `--output-format github` annotation:

```
::error file=some_file.py,line=42,title=my.check.W101::A custom check warning here.
```

2. **`--exit-zero` flag**
Currently, `check` returns a non-zero exit code if it finds any errors. This is often the desired behavior for enforcing code quality. However, for a CI job that just reports on code quality, a non-zero exit code can be undesirable as it will fail the entire job. This proposal suggests adding an optional `--exit-zero` flag.

* With `--exit-zero`, the `check` command will exit with a status code of 0, even if errors or warnings are found.
* A non-zero exit code would only occur if the command terminates abnormally due to an unhandled exception (i.e., not a check violation).

## Use Case Examples

### GitHub Actions Workflow:

```
name: Django Check
on: [push]
jobs:
run-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: pip install -r requirements.txt
- name: Run Django check
run: python manage.py check --output-format github --exit-zero
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.