Path: blob/main/documentation/content/en/books/developers-handbook/policies/_index.po
18099 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-06-29 21:20+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Title = #: documentation/content/en/books/developers-handbook/policies/_index.adoc:1 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:17 #, no-wrap msgid "Source Tree Guidelines and Policies" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/developers-handbook/policies/_index.adoc:1 #, no-wrap msgid "Chapter 5. Source Tree Guidelines and Policies" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:55 msgid "" "This chapter documents various guidelines and policies in force for the " "FreeBSD source tree." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:57 #, no-wrap msgid "Style Guidelines" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:61 msgid "" "Consistent coding style is extremely important, particularly with large " "projects like FreeBSD. Code should follow the FreeBSD coding styles " "described in man:style[9] and man:style.Makefile[5]." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:63 #, no-wrap msgid "`MAINTAINER` on Makefiles" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:67 msgid "" "If a particular portion of the FreeBSD [.filename]#src/# distribution is " "being maintained by a person or group of persons, this is communicated " "through an entry in [.filename]#src/MAINTAINERS#. Maintainers of ports " "within the Ports Collection express their maintainership to the world by " "adding a `MAINTAINER` line to the [.filename]#Makefile# of the port in " "question:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:71 #, no-wrap msgid "MAINTAINER= email-addresses\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:78 msgid "" "For other parts of the repository, or for sections not listed as having a " "maintainer, or when you are unsure who the active maintainer is, try looking " "at the recent commit history of the relevant parts of the source tree. It " "is quite often the case that a maintainer is not explicitly named, but the " "people who are actively working in a part of the source tree for, say, the " "last couple of years are interested in reviewing changes. Even if this is " "not specifically mentioned in the documentation or the source itself, asking " "for a review as a form of courtesy is a very reasonable thing to do." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:81 msgid "The role of the maintainer is as follows:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:83 msgid "" "The maintainer owns and is responsible for that code. This means that he or " "she is responsible for fixing bugs and answering problem reports pertaining " "to that piece of the code, and in the case of contributed software, for " "tracking new versions, as appropriate." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:84 msgid "" "Changes to directories which have a maintainer defined shall be sent to the " "maintainer for review before being committed. Only if the maintainer does " "not respond for an unacceptable period of time, to several emails, will it " "be acceptable to commit changes without review by the maintainer. However, " "it is suggested that you try to have the changes reviewed by someone else if " "at all possible." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:85 msgid "" "It is of course not acceptable to add a person or group as maintainer unless " "they agree to assume this duty. On the other hand it does not have to be a " "committer and it can easily be a group of people." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:87 #, no-wrap msgid "Contributed Software" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:92 msgid "" "Some parts of the FreeBSD distribution consist of software that is actively " "being maintained outside the FreeBSD project. For historical reasons, we " "call this _contributed_ software. Some examples are LLVM, man:zlib[3], and " "man:awk[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:96 msgid "" "The accepted procedure for managing contributed software involves creating a " "_vendor branch_, where the software can be imported cleanly (without " "modification) and updates can be tracked in a versioned manner. Then, the " "content of the vendor branch is applied to the source tree, possibly with " "local modifications. FreeBSD-specific build glue is maintained in the " "source tree, not in the vendor branch." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:100 msgid "" "Depending on their needs and complexity, individual software projects may " "deviate from this procedure, at the discretion of the maintainer. The exact " "steps required to update a particular piece of contributed software should " "be recorded in a file named `FREEBSD-upgrade`; for example, link:https://" "cgit.freebsd.org/src/tree/contrib/libarchive/FREEBSD-upgrade[libarchive's " "FREEBSD-upgrade file]." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:103 msgid "" "Contributed software is usually placed in the [.filepath]#contrib/# " "subdirectory of the source tree, with some exceptions. Contributed software " "used only by the kernel lives under [.filepath]#sys/contrib/#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:107 msgid "" "Because it makes it harder to import future versions minor, trivial and/or " "cosmetic changes are _strongly discouraged_ on files that are still tracking " "the vendor branch." msgstr "" #. type: Title === #: documentation/content/en/books/developers-handbook/policies/_index.adoc:110 #, no-wrap msgid "Vendor Imports" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:113 msgid "" "The standard process for managing contributed software and vendor branches " "is described in detail by the extref:{committers-guide}#vendor-import-" "git[Committer's Guide]." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:115 #, no-wrap msgid "Encumbered Files" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:121 msgid "" "It might occasionally be necessary to include an encumbered file in the " "FreeBSD source tree. For example, if a device requires a small piece of " "binary code to be loaded to it before the device will operate, and we do not " "have the source to that code, then the binary file is said to be " "encumbered. The following policies apply to including encumbered files in " "the FreeBSD source tree." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:123 msgid "" "Any file which is interpreted or executed by the system CPU(s) and not in " "source format is encumbered." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:124 msgid "Any file with a license more restrictive than BSD or GNU is encumbered." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:125 msgid "" "A file which contains downloadable binary data for use by the hardware is " "not encumbered, unless (1) or (2) apply to it." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:126 msgid "" "Any encumbered file requires specific approval from the link:https://" "www.FreeBSD.org/administration/#t-core[Core Team] before it is added to the " "repository." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:127 msgid "" "Encumbered files go in [.filename]#src/contrib# or [.filename]#src/sys/" "contrib#." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:128 msgid "" "The entire module should be kept together. There is no point in splitting " "it, unless there is code-sharing with non-encumbered code." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:130 msgid "" "In the past binary files were typically uuencoded, and named " "[.filename]#arch/filename.o.uu#. This is no longer necessary, and binary " "files may be added to the repository unchanged." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:131 msgid "Kernel files:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:132 msgid "" "Should always be referenced in [.filename]#conf/files.*# (for build " "simplicity)." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:133 msgid "" "Should always be in [.filename]#LINT#, but the link:https://www.FreeBSD.org/" "administration/#t-core[Core Team] decides per case if it should be commented " "out or not. The link:https://www.FreeBSD.org/administration/#t-core[Core " "Team] can, of course, change their minds later on." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:134 msgid "The _Release Engineer_ decides whether or not it goes into the release." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:136 msgid "User-land files:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:137 msgid "" "The link:https://www.FreeBSD.org/administration/#t-core[Core team] decides " "if the code should be part of the installed base system." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:138 msgid "" "The link:https://www.FreeBSD.org/administration/#t-re[Release Engineering] " "decides if it goes into the release." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:140 #, no-wrap msgid "Shared Libraries" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:144 msgid "" "If you are adding shared library support to a port or other piece of " "software that does not have one, the version numbers should follow these " "rules. Generally, the resulting numbers will have nothing to do with the " "release version of the software." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:146 msgid "For ports:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:148 msgid "Prefer using the number already selected by upstream" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:149 msgid "If upstream provides symbol versioning, ensure that we use their script" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:151 msgid "For the base system:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:153 msgid "Start library version from 1" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:154 msgid "It is strongly recommended to add symbol versioning to the new library" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:155 msgid "" "If there is an incompatible change, handle it with symbol versioning, " "maintaining backward ABI compatibility" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:156 msgid "" "If this is impossible, or the library does not use symbol versioning, bump " "the library version" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:157 msgid "" "Before even considering bumping library version for symbol-versioned " "library, consult with Release Engineering team, providing reasons why the " "change is so important that it should be allowed despite breaking the ABI" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:159 msgid "" "For instance, added functions and bugfixes not changing the interfaces are " "fine, while deleted functions, changed function call syntax, etc. should " "either provide backward-compat symbols, or will force the major version " "number to change." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:161 msgid "" "It is the duty of the committer making the change to handle library " "versioning." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:166 msgid "" "The ELF dynamic linker matches library names literally. There is a popular " "convention where library version is written in the form `libexample.so.x.y`, " "where x is the major version, and y is minor. Common practice is to set the " "library' soname (`DT_SONAME` ELF tag) to `libexample.so.x`, and set up " "symlinks `libexample.so.x->libexample.so.x.y`, `libexample.so-" ">libexample.so.x` on library installation for the latest minor version y. " "Then, since the static linker searches for `libexample.so` when the `-" "lexample` command line option is specified, objects linked with libexample " "get a dependency on the right library. Almost all popular build systems use " "this scheme automatically." msgstr ""