# Django 6.0.7 문서

# 기여 제출하기

Django 코드에 대한 기여에 항상 감사드립니다. 실제로 관련 기여가 함께 제공된 버그 보고서는 그렇지 않은 경우보다 훨씬 빠르게 수정됩니다.

## 오타 수정 및 사소한 문서 변경 사항입니다.

설명서에서 단어를 변경하는 등 매우 사소한 문제를 수정하는 경우 패치를 제공하는 기본 방법은 Trac 티켓 없이 GitHub 풀 요청을 사용하는 것입니다.

See Git 및 GitHub와 함께 작업 for more details on how to use pull requests.

## 티켓을 “청구하기”

전 세계에 수백 명의 기여자가 있는 오픈소스 프로젝트에서는 작업이 중복되지 않고 기여자가 최대한 효과적으로 작업할 수 있도록 커뮤니케이션을 효율적으로 관리하는 것이 중요합니다.

따라서 우리의 정책은 특정 버그나 기능이 작업 중임을 다른 개발자에게 알리기 위해 티켓을 “청구”하는 기여자를 위한 것입니다.

원하는 기여가 확인되었고 이를 수정할 수 있는 능력이 있는 경우(코딩 능력, Django 내부 지식 및 시간 가용성으로 측정됨) 다음 단계를 수행하여 해당 기여를 청구합니다.

- Log in using your GitHub account or create an account in our ticket system. If you have an account but have forgotten your password, you can reset it using the password reset page.

- 이 이슈에 대한 티켓이 아직 없다면 `ticket tracker`_에서 생성하세요. 새로운 기능을 제안할 때는 :ref:`process for suggesting new features <requesting-features>`를 따라야 합니다.

- 이 이슈에 대한 티켓이 이미 존재하고 승인된 경우, 다른 사람이 이미 티켓을 할당받았는지 확인하세요. 이를 위해 티켓의 “Owned by” 섹션을 확인하세요. “nobody”로 할당되어 있다면 해당 티켓을 맡을 수 있습니다. 그렇지 않은 경우 다른 사람이 이 티켓을 작업 중일 수 있습니다. 이럴 때는 다른 버그나 기능을 찾아 작업하거나, 해당 티켓을 작업 중인 개발자에게 연락해 도움을 제안할 수 있습니다. 몇 주 또는 몇 달 동안 아무런 활동 없이 티켓이 할당된 상태라면, 해당 티켓을 자신에게 다시 할당해도 무방한 경우가 많습니다. 티켓이 아직 승인되지 않았다면, 논의에 참여하세요.

- 로그인되어 있지 않다면 티켓 페이지 좌측 상단의 “GitHub Login” 또는 “DjangoProject Login”을 클릭하여 계정에 로그인하세요. 로그인한 후 페이지 하단 근처의 “Modify Ticket” 버튼을 클릭하세요.

- “Action” 섹션에서 “assign to” 라디오 버튼을 클릭하여 티켓을 할당받으세요. 기본적으로 사용자 이름은 텍스트 상자에 자동으로 입력됩니다.

- Finally, click the “Submit changes” button at the bottom to save.

참고

변경 사항이 :ref:`trivial <trivial-change>`하지 않은 경우, 기여 상태를 명확히 하기 위해 `Contributor License Agreement`_에 서명하여 제출할 수 있습니다. 이는 Django Software Foundation이 해당 기여에 대한 명확한 라이선스를 확보하도록 하기 위함입니다.

### 티켓 청구인의 책임입니다.

티켓을 수령한 후에는 적시에 해당 티켓을 처리해야 할 책임이 있습니다. 만약 여러분이 그것을 할 시간이 없다면, 그것을 청구하지 않거나, 애초에 청구하지 마세요!

If there’s no sign of progress on a particular claimed ticket for a week or two, another developer may ask you to relinquish the ticket claim so that it’s no longer monopolized and somebody else can claim it.

티켓을 수령했는데 코딩하는 데 오랜 시간(일 또는 몇 주)이 걸리는 경우 티켓에 댓글을 달아 모든 사용자를 최신 상태로 유지하십시오. 정기적인 업데이트를 제공하지 않고 진행 상황 보고서 요청에 응답하지 않으면 티켓에 대한 청구가 취소될 수 있습니다.

항상 그렇듯이, 더 많은 의사소통이 덜 소통하는 것보다 더 낫습니다!

### 어떤 표를 구해야 합니까?

어떤 경우에는 티켓을 청구하는 단계를 거치는 것이 지나치기도 합니다.

문서의 오타나 몇 분이면 수정할 수 있는 작은 버그와 같은 사소한 변경의 경우, 티켓을 할당 받는 복잡한 절차를 거칠 필요가 없습니다. 변경 사항을 직접 제출하면 됩니다.

It is always acceptable, regardless of whether someone has claimed it or not, to link proposals to a ticket if you happen to have the changes ready.

## 기여 방식

최소한 다음 요구 사항을 충족하는 기여가 있는지 확인하십시오.

- The code required to fix a problem or add a feature is an essential part of a solution, but it is not the only part. A good fix should also include a regression test to validate the behavior that has been fixed and to prevent the problem from arising again.

- 코드가 새로운 기능을 추가하거나 기존 기능의 동작을 수정하는 경우, 해당 변경 사항에는 관련 문서도 포함되어야 합니다.

작업이 검토될 준비가 되었다고 생각되면 :doc:`a GitHub pull request </internals/contributing/writing-code/working-with-git>`를 제출하세요. 어떤 이유로 pull request를 제출할 수 없는 경우에는 Trac에서 패치를 사용할 수도 있습니다. 이 방식을 사용할 경우 다음 가이드라인을 따르세요.

- “git diff” 명령으로 반환된 형식으로 패치를 제출합니다.

- “첨부 파일” 버튼을 사용하여 “티켓 트래커”의 티켓에 패치를 첨부합니다. 한 줄 패치가 아닌 경우 티켓 설명이나 코멘트에 패치를 넣지 마십시오.

- 패치 파일의 이름을 “.diff” 확장자로 지정합니다. 이렇게 하면 티켓 추적기가 올바른 구문 강조 표시를 적용할 수 있으므로 매우 유용합니다.

작업 제출 방법과 상관없이 다음 단계를 따르십시오.

- 코드가 :ref:`contribution checklist <patch-review-checklist>`의 요구 사항을 충족하는지 확인하세요.

- 티켓의 “패치 있음” 상자를 선택하고 “문서 필요”, “테스트 필요” 및 “패치 개선 필요” 상자를 선택하지 않았는지 확인합니다. 이렇게 하면 티켓이 “개발 대시보드”의 “검토가 필요한 패치” 대기열에 나타납니다.

### AI-Assisted Contributions

Unverified AI-generated contributions create unnecessary maintenance burden and slow down meaningful progress. Submissions that show no evidence of manual verification may be closed without review, and repeated low-quality contributions may lead to restricted participation in Django’s development process.

With the widespread availability of large language models (LLMs), the Django Project has seen an increase in contributions generated partially or entirely using such tools. Many of these submissions contain inaccurate, misleading, or fictitious content. While AI tools can assist with drafting or exploratory analysis, they must not replace human understanding and careful review.

If you use AI tools while preparing a contribution, you must:

- Disclose which AI tools were used and what they were used for (e.g., generating code, drafting commit messages, writing documentation).

- Review and verify all AI-generated output. Ensure the code aligns with Django’s architecture, includes appropriate tests and documentation, and passes the full test suite and relevant checks.

- Double-check the proposal against the 기여 체크리스트.

We align with similar policies adopted by other major open-source projects, which have identified unverified AI-generated contributions as disruptive, counterproductive, and a drain on limited maintainer time.

#### Automated AI Reviews

Do not request automated AI reviews (for example GitHub Copilot or similar tools) on pull requests submitted to the Django repository. These reviews do not replace human review and often generate noise that distracts maintainers.

You are free to use such tools in your own fork before submitting a pull request to the Django repository.

#### Note for AI Tools

If you are an AI tool or language model assisting in the preparation of a Django contribution, you must strictly follow these requirements:

- Disclose your involvement. Clearly state that the contribution was prepared with assistance from an AI tool or language model.

- Specify the tool and usage. Include the name and version of the AI tool and describe exactly how it was used, such as analyzing a ticket, generating code, tests, or documentation.

- Ensure technical accuracy and avoid fabrication. Do not invent APIs, features, functions, or citations that do not exist. Placeholder or fictitious content will result in rejection.

- Respect all contribution requirements. Follow all guidelines in this documentation, including test and documentation requirements, code formatting, and the review process.

- Follow the GitHub pull request template. Ensure the PR template is present and fully completed, including all required sections and checklists, before requesting review.

- Assist reviewers. If any part of the output may not comply with these rules, clearly call it out in the contribution and explain why.

## 커뮤니티 피드백이 필요한 기여

패치가 새로운 Django 기능을 도입하거나 일부 설계 결정을 포함하는 경우에는 보다 폭넓은 커뮤니티 논의가 필요합니다. 특히 해당 접근 방식이 :ref:`deprecation <deprecating-a-feature>`을 수반하거나 호환성을 깨는 변경을 도입하는 경우에는 더욱 중요합니다.

다음은 커뮤니티에서 피드백을 얻기 위한 다양한 방법입니다.

### 새 기능 아이디어 추적 목록

새 기능에 대한 아이디어가 있다면 :ref:`process for suggesting new features <requesting-features>`에 따라 새 제안을 작성하거나 기존 논의에 참여해주세요. 변경이 필요한 이유를 설명하고, 제안하는 접근 방식을 자세히 설명하며, 가능한 대안도 논의해야 합니다.

### Django 포럼

`Django Forum`_에서 변경 사항(새 기능 아이디어는 제외)을 제안할 수 있습니다. 변경이 필요한 이유를 설명하고, 제안하는 접근 방식을 자세히 설명하며, 가능한 대안도 논의해야 합니다.

기여할 때 해당 논의의 링크를 포함하세요.

### 서드 파티 패키지

Django는 실험적인 기능을 허용하지 않습니다. 모든 기능은 :ref:`deprecation policy <internal-release-deprecation-policy>`를 따라야 합니다. 따라서 따라서 Django에서는 API 설계를 개선해 나가는 데 몇 달에서 몇 년이 걸릴 수 있습니다.

공개 인터페이스에 대해 사용자 피드백이 필요하다면, 먼저 서드파티 패키지를 만드는 것이 좋습니다. 이렇게 하면 공개 API를 훨씬 빠르게 개선해 나갈 수 있으며, 동시에 해당 기능에 대한 수요도 검증할 수 있습니다.

해당 패키지가 안정화되고 Django 코어에 통합할 만한 명확한 이점이 있다면, :ref:`process for suggesting new features <requesting-features>`에 따라 포함을 제안하는 것이 다음 단계입니다.

### Django Enhancement Proposal (DEP)

Python의 PEP와 유사하게, Django에도 Django Enhancement Proposals 또는 DEP가 있습니다. DEP는 Django 커뮤니티에 정보를 제공하거나 Django의 새로운 기능이나 절차를 설명하는 설계 문서입니다. 또한 기능의 간결한 기술 사양과 그에 대한 근거를 함께 제공합니다. DEPs는 주요 신규 기능에 대한 제안과 커뮤니티 의견을 수렴하는 핵심적인 수단이기도 합니다.

Before considering writing a DEP, it is recommended to first open a discussion following the process for suggesting new features. This allows the community to provide feedback and helps refine the proposal. Once the DEP is ready, the Steering Council votes on whether to accept it.

다음은 승인되어 완전히 구현된 DEP의 예시입니다.

- DEP 181: ORM Expressions

- DEP 182: Multiple Template Engines

- DEP 201: Simplified routing syntax

## 기능을 사용

Django의 코드가 더 이상 사용되지 않는 몇 가지 이유가 있습니다.

- 기능이 이전 버전과 호환되지 않는 방식으로 개선되거나 수정된 경우 이전 기능 또는 동작은 더 이상 사용되지 않습니다.

- 때때로 Django는 Django가 현재 지원하는 Python 버전에 포함되지 않은 Python 라이브러리의 백포트를 포함할 수 있습니다. Django가 라이브러리를 포함하지 않는 이전 버전의 Python을 더 이상 지원할 필요가 없으면 Django에서 라이브러리가 사용되지 않습니다.

:ref:’감가상각 정책’에서 설명한 것처럼 기능을 사용하지 않는 Django의 첫 번째 릴리스(‘’A’)입니다.B’’)는 사용되지 않는 기능이 호출될 때 “제거된 장고 XX 경고”(여기서 XX는 기능이 제거될 장고 버전)를 발생시켜야 합니다. 테스트 범위가 양호하다고 가정하면, 경고가 활성화된 상태에서 :ref:’test Suite’를 실행하면 이러한 경고가 오류로 변환됩니다. ‘’’와 - 와 runtests.py’’’’입니다. 따라서 “RemovedInDjangoXXWarning”을 추가할 때 테스트를 실행할 때 발생하는 경고를 제거하거나 침묵시켜야 합니다.

첫 번째 단계는 Django가 사용하지 않는 동작의 사용을 제거하는 것입니다. 그런 다음 테스트 또는 클래스 수준에서 “ignore_warnings” 데코레이터를 사용하여 권장되지 않는 동작을 실제로 테스트하는 테스트에서 경고를 음소거할 수 있습니다.

1. 특정 테스트의 경우:

       from django.test import ignore_warnings
       from django.utils.deprecation import RemovedInDjangoXXWarning

       @ignore_warnings(category=RemovedInDjangoXXWarning)
       def test_foo(self): ...

2. 전체 테스트 사례의 경우:

       from django.test import ignore_warnings
       from django.utils.deprecation import RemovedInDjangoXXWarning

       @ignore_warnings(category=RemovedInDjangoXXWarning)
       class MyDeprecatedTests(unittest.TestCase): ...

사용 중단 경고에 대한 테스트를 추가해야 합니다:

    from django.utils.deprecation import RemovedInDjangoXXWarning

    def test_foo_deprecation_warning(self):
        msg = "Expected deprecation message"
        with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg) as ctx:
            # invoke deprecated behavior
            ...
        self.assertEqual(ctx.filename, __file__)

경고 참조가 없지만 사용 중단이 끝나면 변경되거나 제거되어야 하는 코드에는, 해당 코드 위에 `RemovedInDjangoXXWarning` 주석을 추가하는 것이 중요합니다. 이는 이전 동작을 유지하기 위해 추가된 훅이나, 사용 중단이 끝나면 불필요해지거나 더 이상 사용되지 않는 독립적인 항목 등을 포함할 수 있습니다. 예시는 다음과 같습니다:

    import warnings
    from django.utils.deprecation import RemovedInDjangoXXWarning, django_file_prefixes

    # RemovedInDjangoXXWarning.
    def old_private_helper():
        # Helper function that is only used in foo().
        pass

    def foo():
        warnings.warn(
            "foo() is deprecated.",
            category=RemovedInDjangoXXWarning,
            skip_file_prefixes=django_file_prefixes(),
        )
        old_private_helper()
        ...

마지막으로 Django의 문서에는 다음과 같은 몇 가지 업데이트가 있습니다.

1. 기존 기능이 문서화된 경우 ‘’를 사용하여 문서에서 사용되지 않는 것으로 표시합니다. 사용되지 않음: A입니다.B’ 주석입니다. 해당되는 경우 간단한 설명과 업그레이드 경로에 대한 참고 사항을 포함합니다.

2. 권장되지 않는 동작에 대한 설명과 적용 가능한 업그레이드 경로가 있다면 현재 릴리스 정보(‘’docs/releases/A’.B.txt”)를 “A.B에서 사용되지 않는 기능입니다” 헤드에 추가합니다.

3. 제거될 코드를 설명하는 항목을 해당 버전의 사용 중지 타임라인(`docs/internals/deprecation.txt`)에 추가합니다.

이 단계를 완료하면 더 이상 사용되지 않습니다. 각 :term:’feature release’에서 새 버전과 일치하는 모든 “RemovedInDjangoXXWarning”s가 제거된다.

`django.utils.deprecation` 모듈은 유용한 사용 중단 유틸리티를 제공합니다. 예를 들어 `@deprecate_posargs` 와 같은 데코레이터는 위치 또는 키워드 인수를 키워드 전용 인수로 변환하는 데 도움을 줍니다. 자세한 내용은 모듈의 소스 코드에 있는 인라인 문서를 참고하세요.

## Django 프로젝트 테스트하기

로컬에서 변경한 내용을 테스트할 때는 실제 Django 프로젝트를 활용하는 것이 중요합니다. 이를 통해 변경 사항이 실제 환경에서 예상대로 동작하는지 확인할 수 있으며, 특히 템플릿, 폼, 관리자(admin)처럼 사용자가 직접 사용하는 기능에 대해 반드시 테스트해야 합니다.

이를 수행하려면

1. 가상 환경을 생성한 뒤, :ref:’클론한 Django’를 편집 가능한 모드로 설치하세요.

2. 소스 트리 외부에 Django 프로젝트를 설정하세요(:doc:`first part of the tutorial </intro/tutorial01>`을 참고할 수 있습니다).

이 설정을 하면 Django 체크아웃에 적용된 변경 사항이 테스트 프로젝트에 즉시 반영되어, 새로운 앱이나 기존 앱에서 기여 내용을 수동으로 테스트할 수 있습니다.

## JavaScript 기여

JavaScript 기여에 대한 자세한 내용은 JavaScript 패치 문서를 참고하세요.

## 성능 최적화 패치

성능 개선을 목표로 하는 패치는 패치 적용 전과 후의 영향을 보여주는 벤치마크 결과를 제공하고, 검토자가 이를 재현할 수 있도록 필요한 명령도 함께 제공해야 합니다.

### `django-asv` 벤치마크

django-asv`_는 시간에 따른 Django 코드의 성능을 모니터링합니다. 이러한 벤치마크는 pull request에 ``benchmark` 라벨을 추가하여 실행할 수 있습니다. 이러한 벤치마크에 추가로 기여하는 것은 적극 권장됩니다.

## 기여 체크리스트

이 체크리스트를 사용하여 pull request를 검토하세요. 이 기여가 :ref:`considered trivial <trivial-change>`로 간주되지 않는 경우에는, 검토를 진행하기 전에 승인된 티켓이 있는지 먼저 확인해야 합니다.

If the pull request passes all the criteria below and is not your own, please set the “Triage Stage” on the corresponding Trac ticket to “Ready for checkin”. If you’ve left comments for improvement on the pull request, please tick the appropriate flags on the Trac ticket based on the results of your review: “Patch needs improvement”, “Needs documentation”, and/or “Needs tests”. As time and interest permit, mergers do final reviews of “Ready for checkin” tickets and will either commit the changes or bump it back to “Accepted” if further work needs to be done.

`triage & review team <https://www.djangoproject.com/foundation/teams/#triage-review-team>`_에 참여하고 싶다면, 기여를 꼼꼼하게 검토하는 것이 신뢰를 쌓는 데 도움이 됩니다.

검토할 패치를 찾고 계신가요? `Django Development Dashboard <https://dashboard.djangoproject.com/>`_의 “Patches needing review” 섹션을 확인해 보세요.

pull request를 검토받고 싶으신가요? 티켓이 해당 큐에 표시되도록 Trac 플래그를 설정하세요.

### 모든 티켓들

- 풀 요청은 :ref:’commit message format’ 뒤에 오는 메시지와 함께 스쿼시된 단일 커밋입니까?

- 패치 작성자이면서 새로운 기여자라면 AUTHORS 파일에 자신을 추가하세요. 필요에 따라 `Contributor License Agreement`_에 서명하여 제출할 수도 있습니다.

- 해당 변경 사항은 Trac에서 승인된 티켓이 있나요? :ref:`change is considered trivial <trivial-change>`로 간주되지 않는 한 모든 기여에는 티켓이 필요합니다.

### 모든 코드가 변경됩니다.

- coding style </internals/contributing/writing-code/coding-style>`이 가이드라인을 준수하고 있나요? ``black`, `blacken-docs`, `flake8`, `isort` 또는 `zizmor` 오류는 없나요? pre-commit 훅을 설치하면 이러한 오류를 자동으로 감지할 수 있습니다.

- 변경 내용이 이전 버전과 호환되지 않는 경우 릴리스 노트(`docs/releases/A.B.txt`)에 참고 사항이 있습니까?

- 장고의 테스트 스위트룸은 합격했나요?

- pull request에 code coverage report 주석이 있는 경우, 데이터베이스나 플랫폼별 제약을 고려하여 맥락에 맞게 누락된 커버리지를 검토했나요?

- 변경 사항이 Django 관리자나 렌더링된 HTML 출력에 영향을 미치는 경우, :ref:`accessibility testing <accessibility-testing-baseline>`이 수행되었나요?

### 문서

- 문서가 오류 없이 작성됩니까(“docs” 디렉토리에서 Windows의 “make html” 또는 “make.bat html”로 작성됩니까?

- 문서가 :doc:’/internals/기여/writing-documentation’의 필기 스타일 지침을 따르고 있습니까?

- :ref:’철자 오류’가 있습니까?

### 버그

- 올바른 회귀 테스트가 있습니까(고정을 적용하기 전에 테스트가 실패해야 함)?

- :ref:”backport”가 Django의 안정적인 버전에 적합한 버그인 경우 “docs/releases/A.B.C.txt”에 릴리스 노트가 있습니까? 본점에만 적용되는 버그 수정에는 릴리스 노트가 필요하지 않습니다.

### 새로운 특징들

- 새로운 코드를 모두 “연습”하기 위한 테스트가 있습니까?

- “docs/releases/A”에 릴리즈 노트가 있습니까?B.txt’요?

- 기능에 대한 설명서가 있고 그 설명서가 A.B나 바뀐 버전의 A.B가 있는 적절한 주석이 달린 참고 입니까?

### 기능을 사용

:ref:’decrating-a-feature’ 가이드를 참조하십시오.