diff options
Diffstat (limited to 'documentation/content/en/books/developers-handbook/policies/_index.po')
| -rw-r--r-- | documentation/content/en/books/developers-handbook/policies/_index.po | 396 |
1 files changed, 396 insertions, 0 deletions
diff --git a/documentation/content/en/books/developers-handbook/policies/_index.po b/documentation/content/en/books/developers-handbook/policies/_index.po new file mode 100644 index 0000000000..d2a1565eec --- /dev/null +++ b/documentation/content/en/books/developers-handbook/policies/_index.po @@ -0,0 +1,396 @@ +# 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: 2024-01-17 20:34-0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\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:16 +#, 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:54 +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:56 +#, no-wrap +msgid "Style Guidelines" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:60 +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:62 +#, no-wrap +msgid "`MAINTAINER` on Makefiles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:66 +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:70 +#, no-wrap +msgid "MAINTAINER= email-addresses\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:77 +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:80 +msgid "The role of the maintainer is as follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:82 +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:83 +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:84 +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:86 +#, no-wrap +msgid "Contributed Software" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:91 +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:95 +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:99 +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:102 +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:106 +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:109 +#, no-wrap +msgid "Vendor Imports" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:112 +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:114 +#, no-wrap +msgid "Encumbered Files" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:120 +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:122 +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:123 +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:124 +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:125 +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:126 +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:127 +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:129 +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:130 +msgid "Kernel files:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:131 +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:132 +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:133 +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:135 +msgid "User-land files:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:136 +msgid "" +"The link:https://www.FreeBSD.org/administration/#t-core[Core team] decides " +"if the code should be part of `make world`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:137 +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:139 +#, no-wrap +msgid "Shared Libraries" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:143 +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:145 +msgid "For ports:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:147 +msgid "Prefer using the number already selected by upstream" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:148 +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:150 +msgid "For the base system:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:152 +msgid "Start library version from 1" +msgstr "" + +#. type: Plain text +#: documentation/content/en/books/developers-handbook/policies/_index.adoc:153 +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:154 +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:155 +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:156 +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:158 +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:160 +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:165 +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 "" |