요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
==========
Guidelines
==========
This document describes the general project guidelines that apply to nova-core
and nova-drm.
Language
========
The Nova project uses the Rust programming language. In this context, all rules
of the Rust for Linux project as documented in
:doc:`../../rust/general-information` apply. Additionally, the following rules
apply.
- Unless technically necessary otherwise (e.g. uAPI), any driver code is written
in Rust.
- Unless technically necessary, unsafe Rust code must be avoided. In case of
technical necessity, unsafe code should be isolated in a separate component
providing a safe API for other driver code to use.
Style
-----
All rules of the Rust for Linux project as documented in
:doc:`../../rust/coding-guidelines` apply.
For a submit checklist, please also see the `Rust for Linux Submit checklist
addendum <https://rust-for-linux.com/contributing#submit-checklist-addendum>`_.
Documentation
=============
The availability of proper documentation is essential in terms of scalability,
accessibility for new contributors and maintainability of a project in general,
but especially for a driver running as complex hardware as Nova is targeting.
Hence, adding documentation of any kind is very much encouraged by the project.
Besides that, there are some minimum requirements.
- Every non-private structure needs at least a brief doc comment explaining the
semantical sense of the structure, as well as potential locking and lifetime
requirements. It is encouraged to have the same minimum documentation for
non-trivial private structures.
- uAPIs must be fully documented with kernel-doc comments; additionally, the
semantical behavior must be explained including potential special or corner
cases.
- The APIs connecting the 1st level driver (nova-core) with 2nd level drivers
must be fully documented. This includes doc comments, potential locking and
lifetime requirements, as well as example code if applicable.
- Abbreviations must be explained when introduced; terminology must be uniquely
defined.
- Register addresses, layouts, shift values and masks must be defined properly;
unless obvious, the semantical sense must be documented. This only applies if
the author is able to obtain the corresponding information.
Acceptance Criteria
===================
- Patches must only be applied if reviewed by at least one other person on the
mailing list; this also applies for maintainers.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Rust 언어와 unsafe 경계
1-24이 문서는 `nova-core`와 `nova-drm`에 적용되는 Nova project 공통 guideline입니다. 원문 SPDX 라이선스는 `(GPL-2.0+ OR MIT)`입니다.
Nova project는 Rust programming language를 사용하며 `../../rust/general-information`에 문서화된 Rust for Linux project의 모든 규칙을 적용합니다.
uAPI처럼 기술적으로 다른 선택이 꼭 필요한 경우가 아니면 모든 driver code는 Rust로 작성합니다.
기술적으로 불가피하지 않다면 unsafe Rust code를 피해야 합니다. Unsafe가 필요한 경우 별도 component에 격리하고, 다른 driver code가 사용할 수 있는 safe API를 제공해야 합니다.
Unsafe implementation을 좁은 component 안에 가둡니다.
공통 Rust for Linux 규칙에 추가되는 Nova 원칙입니다.
.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
==========
Guidelines
==========
This document describes the general project guidelines that apply to nova-core
and nova-drm.
Language
========
The Nova project uses the Rust programming language. In this context, all rules
of the Rust for Linux project as documented in
:doc:`../../rust/general-information` apply. Additionally, the following rules
apply.
- Unless technically necessary otherwise (e.g. uAPI), any driver code is written
in Rust.
- Unless technically necessary, unsafe Rust code must be avoided. In case of
technical necessity, unsafe code should be isolated in a separate component
providing a safe API for other driver code to use.
Style과 documentation 최소 요건
25-64Style은 `../../rust/coding-guidelines`의 Rust for Linux 규칙을 모두 따릅니다. 제출 전에는 `https://rust-for-linux.com/contributing#submit-checklist-addendum`의 Submit checklist addendum도 확인합니다.
복잡한 hardware를 다루는 Nova에서 적절한 documentation은 project 확장성, 새 contributor의 접근성, 장기 유지보수에 필수입니다. 따라서 모든 종류의 문서 추가를 적극 권장하며 아래 최소 요건을 적용합니다.
모든 non-private structure에는 semantic purpose와 가능한 locking·lifetime requirement를 설명하는 짧은 doc comment가 최소한 필요합니다. 복잡한 private structure에도 같은 수준의 문서를 권장합니다.
uAPI는 kernel-doc comment로 완전히 문서화해야 하며 특수 상황과 corner case를 포함한 semantic behavior도 설명해야 합니다.
First-level driver인 `nova-core`와 second-level driver를 연결하는 API는 doc comment, locking·lifetime requirement, 적용 가능한 example code를 포함하여 완전히 문서화해야 합니다.
Abbreviation은 처음 도입할 때 설명하고 terminology는 고유하게 정의해야 합니다. Register address·layout·shift·mask도 정확히 정의하며, 의미가 자명하지 않고 author가 정보를 얻을 수 있다면 semantic purpose를 문서화합니다.
대상별로 필요한 계약 정보를 정리합니다.
공개 surface에서 구현 detail로 내려가는 확인 순서입니다.
Style
-----
All rules of the Rust for Linux project as documented in
:doc:`../../rust/coding-guidelines` apply.
For a submit checklist, please also see the `Rust for Linux Submit checklist
addendum <https://rust-for-linux.com/contributing#submit-checklist-addendum>`_.
Documentation
=============
The availability of proper documentation is essential in terms of scalability,
accessibility for new contributors and maintainability of a project in general,
but especially for a driver running as complex hardware as Nova is targeting.
Hence, adding documentation of any kind is very much encouraged by the project.
Besides that, there are some minimum requirements.
- Every non-private structure needs at least a brief doc comment explaining the
semantical sense of the structure, as well as potential locking and lifetime
requirements. It is encouraged to have the same minimum documentation for
non-trivial private structures.
- uAPIs must be fully documented with kernel-doc comments; additionally, the
semantical behavior must be explained including potential special or corner
cases.
- The APIs connecting the 1st level driver (nova-core) with 2nd level drivers
must be fully documented. This includes doc comments, potential locking and
lifetime requirements, as well as example code if applicable.
- Abbreviations must be explained when introduced; terminology must be uniquely
defined.
- Register addresses, layouts, shift values and masks must be defined properly;
unless obvious, the semantical sense must be documented. This only applies if
the author is able to obtain the corresponding information.
Patch acceptance
65-69Patch는 mailing list에서 최소 한 명의 다른 사람이 review한 경우에만 적용할 수 있습니다. 이 규칙은 maintainer에게도 동일하게 적용됩니다.
작성자와 maintainer 모두 독립 review를 거칩니다.
예외 없이 적용되는 review 규칙입니다.
Acceptance Criteria
===================
- Patches must only be applied if reviewed by at least one other person on the
mailing list; this also applies for maintainers.
요약·해설
guidelines.rst:1-69Nova의 Rust 언어, documentation와 patch review 규칙을 정의합니다.
Source와 연결 문서입니다.