# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2022-02-01 09:20-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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 sendmail, gcc and patch." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:94 msgid "" "Over the last couple of years, various methods have been used in dealing " "with this type of software and all have some number of advantages and " "drawbacks. No clear winner has emerged." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:98 msgid "" "Since this is the case, after some debate one of these methods has been " "selected as the \"official\" method and will be required for future imports " "of software of this kind. Furthermore, it is strongly suggested that " "existing contributed software converge on this model over time, as it has " "significant advantages over the old method, including the ability to easily " "obtain diffs relative to the \"official\" versions of the source by everyone " "(even without direct repository access). This will make it significantly " "easier to return changes to the primary developers of the contributed " "software." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:102 msgid "" "Ultimately, however, it comes down to the people actually doing the work. " "If using this model is particularly unsuited to the package being dealt " "with, exceptions to these rules may be granted only with the approval of the " "core team and with the general consensus of the other developers. The " "ability to maintain the package in the future will be a key issue in the " "decisions." 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 with SVN" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:112 msgid "" "This section describes the vendor import procedure with Subversion in " "details." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:115 #, no-wrap msgid "*Preparing the Tree*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:118 msgid "" "If this is your first import after the switch to SVN, you will have to " "flatten and clean up the vendor tree, and bootstrap merge history in the " "main tree. If not, you can safely omit this step." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:122 msgid "" "During the conversion from CVS to SVN, vendor branches were imported with " "the same layout as the main tree. For example, the foo vendor sources ended " "up in [.filename]#vendor/foo/dist/contrib/foo#, but it is pointless and " "rather inconvenient. What we really want is to have the vendor source " "directly in [.filename]#vendor/foo/dist#, like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:131 #, no-wrap msgid "" "% cd vendor/foo/dist/contrib/foo\n" "% svn move $(svn list) ../..\n" "% cd ../..\n" "% svn remove contrib\n" "% svn propdel -R svn:mergeinfo\n" "% svn commit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:135 msgid "" "Note that, the `propdel` bit is necessary because starting with 1.5, " "Subversion will automatically add `svn:mergeinfo` to any directory you copy " "or move. In this case, you will not need this information, since you are " "not going to merge anything from the tree you deleted." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:141 msgid "" "You may want to flatten the tags as well. The procedure is exactly the " "same. If you do this, put off the commit until the end." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:146 msgid "" "Check the [.filename]#dist# tree and perform any cleanup that is deemed to " "be necessary. You may want to disable keyword expansion, as it makes no " "sense on unmodified vendor code. In some cases, it can be even be harmful." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:151 #, no-wrap msgid "" "% svn propdel svn:keywords -R .\n" "% svn commit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:154 msgid "" "Bootstrapping of `svn:mergeinfo` on the target directory (in the main tree) " "to the revision that corresponds to the last change was made to the vendor " "tree prior to importing new sources is also needed:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:160 #, no-wrap msgid "" "% cd head/contrib/foo\n" "% svn merge --record-only ^/vendor/foo/dist@12345678 .\n" "% svn commit\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:163 msgid "" "With some shells, the `^` in the above command may need to be escaped with a " "backslash." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:164 #, no-wrap msgid "*Importing New Sources*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:168 msgid "" "Prepare a full, clean tree of the vendor sources. With SVN, we can keep a " "full distribution in the vendor tree without bloating the main tree. Import " "everything but merge only what is needed." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:171 msgid "" "Note that you will need to add any files that were added since the last " "vendor import, and remove any that were removed. To facilitate this, you " "should prepare sorted lists of the contents of the vendor tree and of the " "sources you are about to import:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:178 #, no-wrap msgid "" "% cd vendor/foo/dist\n" "% svn list -R | grep -v '/$' | sort > ../old\n" "% cd ../foo-9.9\n" "% find . -type f | cut -c 3- | sort > ../new\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:181 msgid "" "With these two files, the following command will list removed files (files " "only in [.filename]#old#):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:185 #, no-wrap msgid "% comm -23 ../old ../new\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:188 msgid "" "While the command below will list added files (files only in [." "filename]#new#):" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:192 #, no-wrap msgid "% comm -13 ../old ../new\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:195 msgid "Let us put this together:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:203 #, no-wrap msgid "" "% cd vendor/foo/foo-9.9\n" "% tar cf - . | tar xf - -C ../dist\n" "% cd ../dist\n" "% comm -23 ../old ../new | xargs svn remove\n" "% comm -13 ../old ../new | xargs svn add\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:210 msgid "" "If there are new directories in the new distribution, the last command will " "fail. You will have to add the directories, and run it again. Conversely, " "if any directories were removed, you will have to remove them manually." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:213 msgid "Check properties on any new files:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:215 msgid "All text files should have `svn:eol-style` set to `native`." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:216 msgid "" "All binary files should have `svn:mime-type` set to `application/octet-" "stream`, unless there is a more appropriate media type." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:217 msgid "Executable files should have `svn:executable` set to `*`." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:218 msgid "There should be no other properties on any file in the tree." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:222 msgid "" "You are ready to commit, but you should first check the output of `svn stat` " "and `svn diff` to make sure everything is in order." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:226 msgid "" "Once you have committed the new vendor release, you should tag it for future " "reference. The best and quickest way is to do it directly in the repository:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:230 #, no-wrap msgid "% svn copy ^/vendor/foo/dist svn_base/vendor/foo/9.9\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:233 msgid "" "To get the new tag, you can update your working copy of [.filename]#vendor/" "foo#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:237 msgid "" "If you choose to do the copy in the checkout instead, do not forget to " "remove the generated `svn:mergeinfo` as described above." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:240 #, no-wrap msgid "*Merging to __-HEAD__*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:243 msgid "" "After you have prepared your import, it is time to merge. Option `--" "accept=postpone` tells SVN not to handle merge conflicts yet, because they " "will be taken care of manually:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:249 #, no-wrap msgid "" "% cd head/contrib/foo\n" "% svn update\n" "% svn merge --accept=postpone ^/vendor/foo/dist\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:252 msgid "" "Resolve any conflicts, and make sure that any files that were added or " "removed in the vendor tree have been properly added or removed in the main " "tree. It is always a good idea to check differences against the vendor " "branch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:256 #, no-wrap msgid "% svn diff --no-diff-deleted --old=^/vendor/foo/dist --new=.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:259 msgid "" "`--no-diff-deleted` tells SVN not to check files that are in the vendor tree " "but not in the main tree." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/developers-handbook/policies/_index.adoc:265 msgid "" "With SVN, there is no concept of on or off the vendor branch. If a file " "that previously had local modifications no longer does, just remove any left-" "over cruft, such as FreeBSD version tags, so it no longer shows up in diffs " "against the vendor tree." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:268 msgid "" "If any changes are required for the world to build with the new sources, " "make them now - and test until you are satisfied that everything build and " "runs correctly." msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:269 #, no-wrap msgid "*Commit*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:275 msgid "" "Now, you are ready to commit. Make sure you get everything in one go. " "Ideally, you would have done all steps in a clean tree, in which case you " "can just commit from the top of that tree. That is the best way to avoid " "surprises. If you do it properly, the tree will move atomically from a " "consistent state with the old code to a consistent state with the new code." msgstr "" #. type: Title == #: documentation/content/en/books/developers-handbook/policies/_index.adoc:277 #, no-wrap msgid "Encumbered Files" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:283 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:285 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:286 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:287 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:288 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:289 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:290 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:292 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:293 msgid "Kernel files:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:294 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:295 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:296 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:298 msgid "User-land files:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:299 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:300 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:302 #, no-wrap msgid "Shared Libraries" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:306 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:308 msgid "For ports:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:310 msgid "Prefer using the number already selected by upstream" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:311 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:313 msgid "For the base system:" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:315 msgid "Start library version from 1" msgstr "" #. type: Plain text #: documentation/content/en/books/developers-handbook/policies/_index.adoc:316 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:317 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:318 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:319 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:321 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:323 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:328 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 ""