Create a distribution Developer Manual

Trivial Changes

Trivial changes are minor, non-substantial changes such as corrections in style, typos, and wording. Trivial edits can be applied directly by assigned reviewers without the need for extensive discussions or announcement on arch-dev-public. The primary goal is to maintain the developer manual's quality while ensuring efficiency in the editing process.

To facilitate the initial creation of this manual, the transfer of pre-existing documentation (at the time of the RFC approval) into the manual shall be counted as a trivial change.

Moderate Changes

Moderate edits include improvements or changes that preserve the established context and overall agreed purpose of content in the manual such as packaging guidelines. An example of this would be adding new flags for reproducible builds or updating existing recommendations to reflect modern practices, while still adhering to the currently established status quo.

Parts that have not yet been specified on a distro level, such as packaging guidelines for a brand new language or tool not yet covered by the core packaging guidelines, can be submitted as moderate change.

All moderate edits MUST be announced on arch-dev-public following a process similar to that used for the RFC, to ensure maximum visibility and community input. The purpose of the announcement is to call for participation to discuss the proposed merge-request on GitLab.

Major changes

These are substantial changes that involve a significant shift in currently established guidelines, workflows or the overall intent of a section. Such changes MUST go through the formal RFC process. This ensures that major changes are thoroughly discussed, reviewed and agreed without bypassing the established RFC process with the developer manual.

If during the course of discussion a moderate change is determined to have a major impact or shift, it should then be reclassified as major change and follow the corresponding process as outlined.

Review

The initial stage of the review process is overseen by a developer manual moderator, whose primary responsibility is to ensure that all discussions adhere to the formalized guidelines and styles of the manual. This role also accepts trivial changes after careful review and approval. Any member of the Arch Linux Staff is eligible to volunteer for this moderator role by proposing themselves on the arch-dev-public mailing list.

To further enhance the quality and relevance of the manual's content, it is essential to explicitly involve domain experts in the review process. Specific topics can have a designated group of experts in their respective fields, that will be auto assigned to issues and merge requests to oversee particular topics by default. For instance, Package Maintainers would be responsible for reviewing and contributing to the sections on packaging guidelines, while ISO and container maintainers would focus on the Release Engineering sections. This increases the visibility of each section and shares the responsibility of the content accuracy and relevance with those who have the most expertise in those areas. The granularity of auto assignment can be fine tuned; for instance, specific language packaging guidelines, such as Rust or Python, can have their own dedicated subgroups.

Any merge-request rejections MUST be accompanied by a comprehensive comment, offering a substantial rationale that forms the foundation for initiating subsequent discussions.