diff options
1181 files changed, 459617 insertions, 35607 deletions
diff --git a/.cirrus.yml b/.cirrus.yml index e828d58f33..591b8e2676 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -1,5 +1,5 @@ freebsd_instance: - image_family: freebsd-13-0-snap + image_family: freebsd-13-2-snap env: CIRRUS_CLONE_DEPTH: 1 diff --git a/.github/conf/label-pull-requests.yml b/.github/conf/label-pull-requests.yml new file mode 100644 index 0000000000..423bb34edc --- /dev/null +++ b/.github/conf/label-pull-requests.yml @@ -0,0 +1,2 @@ +status report: +- website/content/en/status/** diff --git a/.github/workflows/label-pull-requests.yml b/.github/workflows/label-pull-requests.yml new file mode 100644 index 0000000000..49b16db0dd --- /dev/null +++ b/.github/workflows/label-pull-requests.yml @@ -0,0 +1,15 @@ +name: "Label pull requests" +on: [pull_request_target] + +jobs: + + label-pull-requests: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/labeler@v4 + with: + repo-token: "${{ secrets.GITHUB_TOKEN }}" + configuration-path: ".github/conf/label-pull-requests.yml" diff --git a/.hooks/prepare-commit-msg b/.hooks/prepare-commit-msg new file mode 100755 index 0000000000..aec38c7d06 --- /dev/null +++ b/.hooks/prepare-commit-msg @@ -0,0 +1,75 @@ +#!/bin/sh + +# prepare-commit-msg: Prepare a commit message upon `git commit` for the +# user to edit. A script (rather than a static template) is used, so +# that we can insert our template text other than at the top of the +# message. +# +# Install by either setting the configuration of the repository to: +# git config --add core.hooksPath .hooks +# or copy it to the hooks directory, but it will not get automatically updated: +# cp .hooks/prepare-commit-msg .git/hooks/ + +case "$2" in +commit|message) + # It appears git invokes this script for interactive rebase but does + # not remove commented lines, so just exit if we're not called with the + # default (comment-containing) template. + grep -E -q '^#' "$1" || exit 0 + ;; +template) + exit 0 + ;; +merge) + exit 0 + ;; +esac + +outfile=$(mktemp /tmp/freebsd-git-commit.XXXXXXXX) +exec 3> "$outfile" + +# Create a commit message template from three parts: +# +# 1. The beginning of the git-provided template (up to the first comment-only +# line) which explains commented lines and such. +# +# 2. Our template. +# +# 3. The remainder of the git-provided template (from the first comment-only +# line to the end of the file) which lists files staged for commit, files +# not staged, and untracked files. + +awk '1;/^#$/{exit}' "$1" >&3 + +cat >&3 <<EOF +# <Component>: Subject goes here, max 50 cols --| +# <then a blank line> +# 72 columns --| +# +# Do not add a "Submitted by:" line. If someone besides the committer sent in +# the change, the commit author should be set using \`git commit --author\`. +# +# Uncomment and complete these metadata fields, as appropriate: +# +# PR: <If and which Problem Report is related.> +# Reported by: <If someone else reported the issue.> +# Reviewed by: <If someone else reviewed your modification.> +# Tested by: <If someone else tested the change.> +# Approved by: <If you needed approval for this commit.> +# Obtained from: <If the change is from a third party.> +# Fixes: <Short hash and title line of commit fixed by this change> +# Relnotes: <Set to 'yes' for mention in release notes.> +# Security: <Vulnerability reference (one per line) or description.> +# Sponsored by: <If the change was sponsored by an organization.> +# Pull Request: <https://github.com/freebsd/freebsd-doc/pull/###> +# Differential Revision: <https://reviews.freebsd.org/D###> +# +# "Pull Request" and "Differential Revision" require the *full* GitHub or +# Phabricator URL. +EOF + +awk '/^#$/,EOF' "$1" >&3 + +exec 3>&- + +mv "$outfile" "$1" diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..e7657b17a3 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,30 @@ +StylesPath = .vale/styles +MinAlertLevel = suggestion +Vocab = Terms + +[asciidoctor] +# enable +experimental = YES + +# assign a specific value +attribute-missing = drop + +[*.adoc] +BasedOnStyles = FreeBSD, Vale +BlockIgnores = (?s) *(\[\.programlisting\]\n\.{4}.*?\.{4}) + +[{documentation,website}/content/{bn-bd,da,de,el,es,fr,hu,id,it,ja,ko,mn,nl,pl,pt-br,ru,tr,zh-cn,zh-tw}/**/*.adoc] +BasedOnStyles = FreeBSD, Vale +FreeBSD.BrandTerms = NO +FreeBSD.ConsciousLanguage = NO +FreeBSD.Contractions = NO +FreeBSD.Hang = NO +FreeBSD.Hyphens = NO +FreeBSD.Pronouns = NO +FreeBSD.SuperfluousOptArgInLinks = NO +FreeBSD.SemanticLineBreak = NO +FreeBSD.Spacing = NO +Vale.Avoid= NO +Vale.Repetition = NO +Vale.Spelling = NO +Vale.Terms= NO diff --git a/.vale/styles/FreeBSD/BrandTerms.yml b/.vale/styles/FreeBSD/BrandTerms.yml new file mode 100644 index 0000000000..0727760bfe --- /dev/null +++ b/.vale/styles/FreeBSD/BrandTerms.yml @@ -0,0 +1,11 @@ +extends: substitution +message: Use '%s' instead of '%s'. +level: error +ignorecase: true +swap: + '(?:LetsEncrypt|Let''s Encrypt)': Let's Encrypt + 'node[.]?js': Node.js + 'Post?gr?e(?:SQL)': PostgreSQL + 'java[ -]?scripts?': JavaScript + freebsd: FreeBSD + xml: XML diff --git a/.vale/styles/FreeBSD/ConsciousLanguage.yml b/.vale/styles/FreeBSD/ConsciousLanguage.yml new file mode 100644 index 0000000000..24be3d7e59 --- /dev/null +++ b/.vale/styles/FreeBSD/ConsciousLanguage.yml @@ -0,0 +1,36 @@ +--- +extends: substitution +ignorecase: true +level: warning +link: "" +message: Use '%s' rather than '%s.' +action: + name: replace +swap: + black list: blocklist|wronglist|banlist|deny list + blacklist: blocklist|wronglist|banlist|deny list + blacklisted: blocklisted|wronglisted|banlisted|deny-listed + blacklisting: blocklisting|wronglisting|banlisting|deny-listing + bugreport: bug report|snapshot + ghetto: projects|urban + grandfather clause: legacy policy|legacy clause|deprecation policy + grandfather policy: legacy policy|legacy clause|deprecation policy + grandfathered: deprecated + grandfathering: deprecate + master: primary|hub|source|initiator|requester|controller|host|director|reference + masters: primaries|hubs|references + non white: person of color|people of color + nonwhite: person of color|people of color + sophisticated culture: complex culture + sophisticated technology: complex technology + stone age: simple|indigenous|hunter-gatherer + slave: secondary|replica|responder|device|worker|proxy|performer + totem: favorite|inspiration|personal interest|personality type + white list: passlist|alrightlist|safelist|allow list + white space: space|blank + white spaces: spaces|blanks + whitelist: passlist|alrightlist|safelist|allow list + whitelisted: passlisted|alrightlisted|safelisted|allow-listed + whitelisting: passlisting|alrightlisting|safelisting|allow-listing + whitespace: space|blank + whitespaces: spaces|blanks diff --git a/.vale/styles/FreeBSD/Contractions.yml b/.vale/styles/FreeBSD/Contractions.yml new file mode 100644 index 0000000000..3af60259eb --- /dev/null +++ b/.vale/styles/FreeBSD/Contractions.yml @@ -0,0 +1,42 @@ +--- +extends: substitution +ignorecase: true +level: suggestion +message: "Avoid contractions. Use '%s' rather than '%s.'" +action: + name: replace +swap: + "aren't": is not + "can't": cannot + "couldn't": could not + "didn't": did not + "doesn't": does not + "don't": do not + "hasn't": has not + "haven't": have not + "how'll": how will + "how's": how is + "isn't": is not + "it'll": it will + "it's": it is + "shouldn't": should not + "that'll": that will + "that's": that is + "they'll": they will + "they're": they are + "wasn't": was not + "we'll": we will + "we're": we are + "we've": we have + "weren't": were not + "what'll": what will + "what's": what is + "when'll": when will + "when's": when is + "where'll": where will + "where's": where is + "who'll": who will + "who's": who is + "why'll": why will + "why's": why is + "won't": will not diff --git a/.vale/styles/FreeBSD/EOLSpacing.yml b/.vale/styles/FreeBSD/EOLSpacing.yml new file mode 100644 index 0000000000..ea1d57e8ca --- /dev/null +++ b/.vale/styles/FreeBSD/EOLSpacing.yml @@ -0,0 +1,7 @@ +--- +extends: existence +message: "End of lines should not have spaces" +level: warning +scope: raw +raw: + - ' +\n' diff --git a/.vale/styles/FreeBSD/Hang.yml b/.vale/styles/FreeBSD/Hang.yml new file mode 100644 index 0000000000..f4a1447905 --- /dev/null +++ b/.vale/styles/FreeBSD/Hang.yml @@ -0,0 +1,12 @@ +--- +extends: substitution +message: When referring to application, consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + hang: the app froze|the app stopped responding|the app stopped responding to events|the + app became unresponsive + hanged: the app froze|the app stopped responding|the app stopped responding to events|the + app became unresponsive diff --git a/.vale/styles/FreeBSD/Hyphens.yml b/.vale/styles/FreeBSD/Hyphens.yml new file mode 100644 index 0000000000..f40479e426 --- /dev/null +++ b/.vale/styles/FreeBSD/Hyphens.yml @@ -0,0 +1,13 @@ +extends: existence +message: "'%s' doesn't need a hyphen." +level: warning +ignorecase: false +nonword: true +action: + name: edit + params: + - replace + - '-' + - ' ' +tokens: + - '\s[^\s-]+ly-' diff --git a/.vale/styles/FreeBSD/Pronouns.yml b/.vale/styles/FreeBSD/Pronouns.yml new file mode 100644 index 0000000000..15d8352874 --- /dev/null +++ b/.vale/styles/FreeBSD/Pronouns.yml @@ -0,0 +1,24 @@ +--- +extends: existence +message: "Avoid pronouns such as '%s'." +ignorecase: true +level: warning +nonword: true +tokens: + - (?:^|\s)I\s + - (?:^|\s)I,\s + - \bI'm\b + - \bme\b + - \bmy\b + - \bmine\b + - he/she + - s/he + - \(s\)he + - we + - we'(?:ve|re) + - ours? + - us + - let's + - you + - yours? + - you'(?:ve|re) diff --git a/.vale/styles/FreeBSD/SemanticLineBreak.yml b/.vale/styles/FreeBSD/SemanticLineBreak.yml new file mode 100644 index 0000000000..3c685c970c --- /dev/null +++ b/.vale/styles/FreeBSD/SemanticLineBreak.yml @@ -0,0 +1,8 @@ +extends: occurrence +message: "Only use one sentence per line." +level: suggestion +scope: + - paragraph + - list +max: 1 +token: '(?<!Inc|e\.g)[.!?](?: |$)' diff --git a/.vale/styles/FreeBSD/Spacing.yml b/.vale/styles/FreeBSD/Spacing.yml new file mode 100644 index 0000000000..ab716c0e68 --- /dev/null +++ b/.vale/styles/FreeBSD/Spacing.yml @@ -0,0 +1,7 @@ +extends: existence +message: "'%s' should have one space." +level: error +nonword: true +tokens: + - '[a-z][.?!] {2,}[A-Z]' + - '[a-z][.?!][A-Z]' diff --git a/.vale/styles/FreeBSD/SuperfluousOptArgInLinks.yml b/.vale/styles/FreeBSD/SuperfluousOptArgInLinks.yml new file mode 100644 index 0000000000..36b2b4158b --- /dev/null +++ b/.vale/styles/FreeBSD/SuperfluousOptArgInLinks.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Displayed text coincides with URL, leave the brackets empty: %s" +ignorecase: true +level: suggestion +scope: raw +raw: + - 'link:([^ ]*)\/?\[\1\/?\]' diff --git a/.vale/styles/Vocab/Terms/accept.txt b/.vale/styles/Vocab/Terms/accept.txt new file mode 100644 index 0000000000..db89dd2f8e --- /dev/null +++ b/.vale/styles/Vocab/Terms/accept.txt @@ -0,0 +1,183 @@ +(?i)bpf +(?:je|tc)malloc +AMCC\'s +APIs? +Adaptec +Belkin +Biba +Broadcom +CPUs? +DTDs +DTrace +FreeBSD +Heimdal +Hhook +KPIs? +Lua +MFC +Mellanox +Mylex +NVMe +Novell +OIDs? +Qlogic +Radeon +Redistributions +SMBus +SMPng +Safeport +Setkey +USB +VIMAGE +[Bb]inutil +[Cc]allouts? +[Dd]atagram +[Dd]eallocat(?:e|ion) +[Dd]evfs +[Dd]ummynet +[Ff]ramebuffer +[Jj]ourna(?:led|ling) +[Kk]help +[Kk]obj +[M]akefile +[Mm]map +[Mm]ulticast +[Nn]et(?:graph|map) +[Pp]ort(?:clippy|fmt|lint) +[Uu]serland +[Vv]irtualiz(?:ation|es|ed|ing) +[Vv]node +arg +armeb +ath +backout +backport +bool +bsdiff +busdma +byacc +cdev +cdevsw +config +conformant +const +cpufreq +crt(?:begin|end) +crypto +ctype +cutover +deanonymizing +demultiplexer +dereference +devclass +disklabel +distfiles? +dpcpu +drm +enums +errno +fileops +filedesc +fusefs +gcc +glibc +gperf +gpreg +gtar +gzip(?:\'ed) +iconv +if(?:_bridge|lib|net) +inlining +inode +ioctls +klds? +kqueue +krpc +kyua +ldconfig +libc +libdialog +libdwarf +libmap +libncurses +libtinfow +libunwind +libutil +lib(?:alias|elf|lzma|m|md|objc|pam|pcap|pthread|thr|ulog|utempter) +lldb? +llvm +lockless +lookups +lzma +manpage +makefs +mbuf +mips +mountd +mtree +multibyte +multilabel +multithrea(?:d|ded|ding) +musl +mutex +namespace +ncurses +netisrs? +newbus +newsyslog +nfscommon +nfsd +nfsserver +openmp +passthrough +patchlevel +pcb +pfil +pmc +portlint +portsnap +powerpc +powerstate +procfs +plist +pluggable +poudriere +pkg_install +readline +reentrant +reimplement(?:ation|ed|ing) +rtld +s?rc +securelevels? +sed +sleepable +smbfs +stacksizes? +statfs +syscall +sysctl +sysctl\'s +sysfs +tcpdump +tcsh +teardown +tickless +trapframe +tunables +twe +uid +unbreaking +unloadable +unwiring +userspace +vectorizer +vflush +vfs +vfs_mount +vnet +vp +wakeup +xz +yacc +zfs +zlib diff --git a/.vale/vale.tmpl b/.vale/vale.tmpl new file mode 100644 index 0000000000..0ed6301df7 --- /dev/null +++ b/.vale/vale.tmpl @@ -0,0 +1,40 @@ +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} +{{$table := newTable true}} + +{{- $f = add1 $f -}} +{{- .Path | underline | indent 1 -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- $loc := printf "%d:%d" .Line (index .Span 0) -}} +{{- $row := list $loc $error .Message .Check | toStrings -}} + +{{- $table = addRow $table $row -}} +{{end -}} + +{{- $table = renderTable $table -}} +{{end}} +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}} and {{$s}} {{"suggestions" | blue}} in {{$f}} {{$f | int | plural "file" "files"}}. @@ -1,4 +1,4 @@ -Copyright 1994-2022 The FreeBSD Project. All rights reserved. +Copyright 1994-2023 The FreeBSD Project. Redistribution and use in source (AsciiDoc) and 'compiled' forms (HTML, PDF, EPUB and so forth) with or without modification, are permitted provided that @@ -18,4 +18,7 @@ SUBDIR+= website SUBDIR_PARALLEL= yes +run: + @(echo The 'run' target is only valid in a subdirectory; exit 1) + .include <bsd.subdir.mk> diff --git a/documentation/Makefile b/documentation/Makefile index 457f6add0b..825c235269 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,7 +1,7 @@ # Generate the FreeBSD documentation # -# Copyright (c) 2020-2022, The FreeBSD Documentation Project -# Copyright (c) 2020-2022, Sergio Carlavilla <carlavilla@FreeBSD.org> +# Copyright (c) 2020-2023, The FreeBSD Documentation Project +# Copyright (c) 2020-2023, Sergio Carlavilla <carlavilla@FreeBSD.org> # # Targets intended for use on the command line # @@ -32,13 +32,23 @@ BOOKONLY_LANGS= mn ALL_LANGUAGES= bn-bd da de el en es fr hu id it ja ko mn nl pl pt-br ru tr zh-cn zh-tw LOCALBASE?= /usr/local +USE_RUBYGEMS?= NO +GEM_PATH?= -RUBY_CMD = ${LOCALBASE}/bin/ruby +.if ${USE_RUBYGEMS} == "YES" +GEMBASE?= ${GEM_PATH} +.else +GEMBASE?= ${LOCALBASE} +.endif + +RUBY_CMD = ${GEMBASE}/bin/ruby HUGO_CMD = ${LOCALBASE}/bin/hugo -HUGO_ARGS?= --verbose --minify +HUGO_ARGS?= --minify HUGO_OFFLINE_ARGS?= --environment offline --verbose --minify -ASCIIDOCTOR_CMD= ${LOCALBASE}/bin/asciidoctor -ASCIIDOCTORPDF_CMD= ${LOCALBASE}/bin/asciidoctor-pdf +ROUGIFY_CMD= ${GEMBASE}/bin/rougify +ASCIIDOCTOR_CMD= ${GEMBASE}/bin/asciidoctor +ASCIIDOCTORPDF_CMD= ${GEMBASE}/bin/asciidoctor-pdf +ASCIIDOCTOREPUB3_CMD= ${GEMBASE}/bin/asciidoctor-epub3 .if defined(DOC_LANG) && !empty(DOC_LANG) LANGUAGES= ${DOC_LANG:S/,/ /g} @@ -54,8 +64,8 @@ RUBYLIB = ../shared/lib .export RUBYLIB RUN_DEPENDS= ${HUGO_CMD} \ - ${LOCALBASE}/bin/asciidoctor \ - ${LOCALBASE}/bin/rougify + ${ASCIIDOCTOR_CMD} \ + ${ROUGIFY_CMD} .ifndef HOSTNAME . ifdef BIND @@ -111,13 +121,13 @@ requirements: .endfor requirements-pdf: -.if !exists(${LOCALBASE}/bin/asciidoctor-pdf) - @(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1) +.if !exists(${ASCIIDOCTORPDF_CMD}) + @(echo ${ASCIIDOCTOR_CMD} not found, please install rubygem-asciidoctor-pdf; exit 1) .endif requirements-epub: -.if !exists(${LOCALBASE}/bin/asciidoctor-epub3) - @(echo ${LOCALBASE}/bin/asciidoctor-epub3 not found, please run 'pkg install rubygem-asciidoctor-epub3'; exit 1) +.if !exists(${ASCIIDOCTOREPUB3_CMD}) + @(echo ${ASCIIDOCTOREPUB3_CMD} not found, please install rubygem-asciidoctor-epub3; exit 1) .endif starting-message: .PHONY diff --git a/documentation/config/_default/config.toml b/documentation/config/_default/config.toml index 087c0f5576..6949019e99 100644 --- a/documentation/config/_default/config.toml +++ b/documentation/config/_default/config.toml @@ -12,6 +12,7 @@ authors = [ "carlavilla@FreeBSD.org" ] ignoreFiles = [ "chapter.adoc$", "contrib-386bsd.adoc$", "contrib-additional.adoc$", "contrib-committers.adoc$", "contrib-corealumni.adoc$", "contrib-develalumni.adoc$", "contrib-develinmemoriam.adoc$", "contrib-portmgralumni.adoc$", "\\.po$" ] enableRobotsTXT = true enableGitInfo = true +timeout = 180000 [params] websiteURL = "https://www.FreeBSD.org" @@ -37,6 +38,7 @@ enableGitInfo = true env-beastie = true isOnline = true skip-front-matter = true + sectanchors = "after" [outputs] home = [ "HTML" ] diff --git a/documentation/config/offline/config.toml b/documentation/config/offline/config.toml index 653ef5b279..c0ac70a72a 100644 --- a/documentation/config/offline/config.toml +++ b/documentation/config/offline/config.toml @@ -12,6 +12,7 @@ authors = [ "carlavilla@FreeBSD.org" ] ignoreFiles = [ "chapter.adoc$", "contrib-386bsd.adoc$", "contrib-additional.adoc$", "contrib-committers.adoc$", "contrib-corealumni.adoc$", "contrib-develalumni.adoc$", "contrib-develinmemoriam.adoc$", "contrib-portmgralumni.adoc$", "books.adoc$", "\\.po$" ] enableRobotsTXT = true relativeURLs = true +timeout = 180000 [params] websiteURL = "https://www.FreeBSD.org" diff --git a/documentation/content/de/books/handbook/config/_index.adoc b/documentation/content/de/books/handbook/config/_index.adoc index c3ca5b53f3..3bfdc51759 100644 --- a/documentation/content/de/books/handbook/config/_index.adoc +++ b/documentation/content/de/books/handbook/config/_index.adoc @@ -1523,5 +1523,5 @@ Obwohl die meisten Entwickler die Mailingliste {freebsd-current} lesen, sollten Weitere Informationen über ACPI finden Sie hier: * Die FreeBSD ACPI Mailingliste (https://lists.freebsd.org/pipermail/freebsd-acpi/[https://lists.freebsd.org/pipermail/freebsd-acpi/]) -* Die ACPI 2.0 Spezifikation (http://acpi.info/spec.htm[http://acpi.info/spec.htm]) +* Die https://uefi.org/specifications#ACPI[ACPI Spezifikation] * man:acpi[4], man:acpi_thermal[4], man:acpidump[8], man:iasl[8] und man:acpidb[8] diff --git a/documentation/content/de/books/handbook/l10n/_index.adoc b/documentation/content/de/books/handbook/l10n/_index.adoc index f8d6dcc44a..d047846a7c 100644 --- a/documentation/content/de/books/handbook/l10n/_index.adoc +++ b/documentation/content/de/books/handbook/l10n/_index.adoc @@ -361,7 +361,7 @@ mousechar_start=3 === Einrichtung von Xorg -crossref:x11[x11,Das X-Window-System] beschreibt die Installation und Konfiguration von Xorg. Wenn Xorg für die Lokalisierung eingerichtet wird, stehen zusätzliche Zeichensätze und Eingabemethoden in der FreeBSD Ports-Sammlung zur Verfügung. Anwendungsspezifische I18N-Einstellungen, wie etwa Zeichensätze und Menüs, können in [.filename]#~/.Xresouces# angepasst werden, damit in den graphischen Anwendungen des Benutzers die gewählte Sprache angezeigt wird. +crossref:x11[x11,Das X-Window-System] beschreibt die Installation und Konfiguration von Xorg. Wenn Xorg für die Lokalisierung eingerichtet wird, stehen zusätzliche Zeichensätze und Eingabemethoden in der FreeBSD Ports-Sammlung zur Verfügung. Anwendungsspezifische I18N-Einstellungen, wie etwa Zeichensätze und Menüs, können in [.filename]#~/.Xresources# angepasst werden, damit in den graphischen Anwendungen des Benutzers die gewählte Sprache angezeigt wird. Das X Input Method (XIM) Protokoll ist ein Xorg-Standard für die Eingabe von nicht-englischen Zeichen. <<locale-xim>> fasst die aus der FreeBSD Ports-Sammlung verfügbaren Anwendungen für die Eingabemethoden zusammen. Zusätzliche Fcitx- und Uim-Anwendungen sind ebenfalls verfügbar. [[locale-xim]] diff --git a/documentation/content/de/books/handbook/pgpkeys/_index.adoc b/documentation/content/de/books/handbook/pgpkeys/_index.adoc index 92bc2cf2d1..5b35e00f3a 100644 --- a/documentation/content/de/books/handbook/pgpkeys/_index.adoc +++ b/documentation/content/de/books/handbook/pgpkeys/_index.adoc @@ -59,9 +59,6 @@ Verwenden Sie die nachstehenden Schlüssel, wenn Sie eine Signatur überprüfen === {security-officer-name} `<{security-officer-email}>` include::{pgpkeys-path}static/pgpkeys/security-officer.key[] -=== {secteam-secretary-name} `<{secteam-secretary-email}>` -include::{pgpkeys-path}static/pgpkeys/secteam-secretary.key[] - === {core-secretary-name} `<{core-secretary-email}>` include::{pgpkeys-path}static/pgpkeys/core-secretary.key[] diff --git a/documentation/content/de/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/de/books/porters-handbook/pkg-files/_index.adoc index e5ec5b10af..8ba50d28c3 100644 --- a/documentation/content/de/books/porters-handbook/pkg-files/_index.adoc +++ b/documentation/content/de/books/porters-handbook/pkg-files/_index.adoc @@ -66,6 +66,14 @@ update-etc-shells: [NOTE] ==== +Stellen Sie sicher, dass sie auf die korrekten Tools zum Verwalten von Diensten verweisen. +* Verwenden Sie `service name start`, um einen Dienst zu starten, anstatt `/usr/local/etc/rc.d/name start` zu verwenden. +* Verwenden Sie `sysrc name_enable=YES`, um Optionen in rc.conf zu ändern. + +==== + +[NOTE] +==== Die [.filename]#pkg-message# wird nicht zur [.filename]#pkg-plist# hinzugefügt. Sie wird auch nicht automatisch angezeigt, falls ein Anwender den Port installiert. Sie müssen also die Ausgabe selbst im `post-install`-Ziel des Make-Vorgangs veranlassen. ==== diff --git a/documentation/content/el/books/faq/_index.adoc b/documentation/content/el/books/faq/_index.adoc index eedac8c88f..bd000063ee 100644 --- a/documentation/content/el/books/faq/_index.adoc +++ b/documentation/content/el/books/faq/_index.adoc @@ -1660,7 +1660,7 @@ First, always make sure that you have a completely up-to-date Ports Collection. However, if you are up-to-date, perhaps you are seeing another problem. `make index` has a known bug in dealing with incomplete copies of the Ports Collection. It assumes that you have a local copy of every single port that every other port that you have a local copy of depends on. To explain, if you have a copy of [.filename]#foo/bar# on your disk, and [.filename]#foo/bar# depends on [.filename]#baz/quux#, then you must also have a copy of [.filename]#baz/quux# on your disk, and the ports [.filename]#baz/quux# depends on, and so on. Otherwise, `make index` has insufficient information to create its dependency tree. -This is particularly a problem for FreeBSD users who utilize man:cvsup[1] to track the Ports Collection but choose not to install certain categories by specifying them in [.filename]#refuse#. In theory, one should be able to refuse categories, but in practice there are too many ports that depend on ports in other categories. Until someone comes up with a solution for this problem, the general rule is is that if you want to build [.filename]#INDEX#, you must have a complete copy of the Ports Collection. +This is particularly a problem for FreeBSD users who utilize man:cvsup[1] to track the Ports Collection but choose not to install certain categories by specifying them in [.filename]#refuse#. In theory, one should be able to refuse categories, but in practice there are too many ports that depend on ports in other categories. Until someone comes up with a solution for this problem, the general rule is that if you want to build [.filename]#INDEX#, you must have a complete copy of the Ports Collection. There are rare cases where [.filename]#INDEX# will not build due to odd cases involving `WITH__*_` or `WITHOUT__*_` variables being set in [.filename]#make.conf#. If you suspect that this is the case, please try to make [.filename]#INDEX# with those Makevars turned off before reporting it to {freebsd-ports}. diff --git a/documentation/content/el/books/handbook/config/_index.adoc b/documentation/content/el/books/handbook/config/_index.adoc index 3460bb661d..6449b7545f 100644 --- a/documentation/content/el/books/handbook/config/_index.adoc +++ b/documentation/content/el/books/handbook/config/_index.adoc @@ -1369,6 +1369,6 @@ More information about ACPI may be found in the following locations: * The {freebsd-acpi} * The ACPI Mailing List Archives http://lists.freebsd.org/pipermail/freebsd-acpi/[http://lists.freebsd.org/pipermail/freebsd-acpi/] * The old ACPI Mailing List Archives http://home.jp.FreeBSD.org/mail-list/acpi-jp/[http://home.jp.FreeBSD.org/mail-list/acpi-jp/] -* The ACPI 2.0 Specification http://acpi.info/spec.htm[http://acpi.info/spec.htm] +* The https://uefi.org/specifications#ACPI[ACPI Specification] * FreeBSD Manual pages: man:acpi[4], man:acpi_thermal[4], man:acpidump[8], man:iasl[8], man:acpidb[8] * http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt[DSDT debugging resource]. (Uses Compaq as an example but generally useful.) diff --git a/documentation/content/el/books/handbook/pgpkeys/_index.adoc b/documentation/content/el/books/handbook/pgpkeys/_index.adoc index d00364b3a8..bfa3d56fbf 100644 --- a/documentation/content/el/books/handbook/pgpkeys/_index.adoc +++ b/documentation/content/el/books/handbook/pgpkeys/_index.adoc @@ -59,9 +59,6 @@ endif::[] === {security-officer-name} `<{security-officer-email}>` include::{pgpkeys-path}static/pgpkeys/security-officer.key[] -=== {secteam-secretary-name} `<{secteam-secretary-email}>` -include::{pgpkeys-path}static/pgpkeys/secteam-secretary.key[] - === {core-secretary-name} `<{core-secretary-email}>` include::{pgpkeys-path}static/pgpkeys/core-secretary.key[] diff --git a/documentation/content/el/books/handbook/security/_index.adoc b/documentation/content/el/books/handbook/security/_index.adoc index 33114a15cf..615a41c964 100644 --- a/documentation/content/el/books/handbook/security/_index.adoc +++ b/documentation/content/el/books/handbook/security/_index.adoc @@ -189,7 +189,7 @@ A good security script will also check for changes to user and staff members acc If you have a huge amount of user disk space, it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The `nodev` and `nosuid` options (see man:mount[8]) are what you want to look into. You should probably scan them anyway, at least once a week, since the object of this layer is to detect a break-in attempt, whether or not the attempt succeeds. -Process accounting (see man:accton[8]) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in has occured. +Process accounting (see man:accton[8]) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in has occurred. Finally, security scripts should process the log files, and the logs themselves should be generated in as secure a manner as possible - remote syslog can be very useful. An intruder will try to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information to a secure machine monitoring the consoles. diff --git a/documentation/content/en/articles/_index.po b/documentation/content/en/articles/_index.po new file mode 100644 index 0000000000..42a0aa133d --- /dev/null +++ b/documentation/content/en/articles/_index.po @@ -0,0 +1,29 @@ +# 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: 2022-01-08 11: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/articles/_index.adoc:1 +#: documentation/content/en/articles/_index.adoc:6 +#, no-wrap +msgid "Articles" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/_index.adoc:8 +msgid "{{< list-articles-directories >}}" +msgstr "" diff --git a/documentation/content/en/articles/bsdl-gpl/_index.po b/documentation/content/en/articles/bsdl-gpl/_index.po new file mode 100644 index 0000000000..54a98693aa --- /dev/null +++ b/documentation/content/en/articles/bsdl-gpl/_index.po @@ -0,0 +1,780 @@ +# 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: 2022-02-01 09:21-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/articles/bsdl-gpl/_index.adoc:1 +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:11 +#, no-wrap +msgid "Why you should use a BSD style license for your Open Source Project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:43 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:47 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:52 +msgid "" +"This document makes a case for using a BSD style license for software and " +"data; specifically it recommends using a BSD style license in place of the " +"GPL. It can also be read as a BSD versus GPL Open Source License " +"introduction and summary." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:54 +#, no-wrap +msgid "Very Brief Open Source History" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:60 +msgid "" +"Long before the term \"Open Source\" was used, software was developed by " +"loose associations of programmers and freely exchanged. Starting in the " +"early 1950's, organizations such as http://www.share.org[SHARE] and http://" +"www.decus.org[DECUS] developed much of the software that computer hardware " +"companies bundled with their hardware offerings. At that time computer " +"companies were in the hardware business; anything that reduced software cost " +"and made more programs available made the hardware companies more " +"competitive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:67 +msgid "" +"This model changed in the 1960's. In 1965 ADR developed the first licensed " +"software product independent of a hardware company. ADR was competing " +"against a free IBM package originally developed by IBM customers. ADR " +"patented their software in 1968. To stop sharing of their program, they " +"provided it under an equipment lease in which payment was spread over the " +"lifetime of the product. ADR thus retained ownership and could control " +"resale and reuse." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:70 +msgid "" +"In 1969 the US Department of Justice charged IBM with destroying businesses " +"by bundling free software with IBM hardware. As a result of this suit, IBM " +"unbundled its software; that is, software became independent products " +"separate from hardware." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:75 +msgid "" +"In 1968 Informatics introduced the first commercial killer-app and rapidly " +"established the concept of the software product, the software company, and " +"very high rates of return. Informatics developed the perpetual license " +"which is now standard throughout the computer industry, wherein ownership is " +"never transferred to the customer." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:77 +#, no-wrap +msgid "Unix from a BSD Licensing Perspective" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:83 +msgid "" +"AT&T, who owned the original Unix implementation, was a publicly regulated " +"monopoly tied up in anti-trust court; it was legally unable to sell a " +"product into the software market. It was, however, able to provide it to " +"academic institutions for the price of media." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:89 +msgid "" +"Universities rapidly adopted Unix after an OS conference publicized its " +"availability. It was extremely helpful that Unix ran on the PDP-11, a very " +"affordable 16-bit computer, and was coded in a high-level language that was " +"demonstrably good for systems programming. The DEC PDP-11 had, in effect, " +"an open hardware interface designed to make it easy for customers to write " +"their own OS, which was common. As DEC founder Ken Olsen famously " +"proclaimed, \"software comes from heaven when you have good hardware\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:95 +msgid "" +"Unix author Ken Thompson returned to his alma mater, University of " +"California Berkeley (UCB), in 1975 and taught the kernel line-by-line. This " +"ultimately resulted in an evolving system known as BSD (Berkeley Standard " +"Distribution). UCB converted Unix to 32-bits, added virtual memory, and " +"implemented the version of the TCP/IP stack upon which the Internet was " +"essentially built. UCB made BSD available for the cost of media, under what " +"became known as \"the BSD license\". A customer purchased Unix from AT&T " +"and then ordered a BSD tape from UCB." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:99 +msgid "" +"In the mid-1980s a government anti-trust case against AT&T ended with the " +"break-up of AT&T. AT&T still owned Unix and was now able to sell it. AT&T " +"embarked on an aggressive licensing effort and most commercial Unixes of the " +"day became AT&T-derived." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:105 +msgid "" +"In the early 1990's AT&T sued UCB over license violations related to BSD. " +"UCB discovered that AT&T had incorporated, without acknowledgment or " +"payment, many improvements due to BSD into AT&T's products, and a lengthy " +"court case, primarily between AT&T and UCB, ensued. During this period some " +"UCB programmers embarked on a project to rewrite any AT&T code associated " +"with BSD. This project resulted in a system called BSD 4.4-lite (lite " +"because it was not a complete system; it lacked 6 key AT&T files)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:109 +msgid "" +"A lengthy series of articles published slightly later in Dr. Dobbs magazine " +"described a BSD-derived 386 PC version of Unix, with BSD-licensed " +"replacement files for the 6 missing 4.4 lite files. This system, named " +"386BSD, was due to ex-UCB programmer William Jolitz. It became the original " +"basis of all the PC BSDs in use today." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:112 +msgid "" +"In the mid 1990s, Novell purchased AT&T's Unix rights and a (then secret) " +"agreement was reached to terminate the lawsuit. UCB soon terminated its " +"support for BSD." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:114 +#, no-wrap +msgid "The Current State of FreeBSD and BSD Licenses" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:120 +msgid "" +"The so-called http://www.opensource.org/licenses/bsd-license.php[new BSD " +"license] applied to FreeBSD within the last few years is effectively a " +"statement that you can do anything with the program or its source, but you " +"do not have any warranty and none of the authors has any liability " +"(basically, you cannot sue anybody). This new BSD license is intended to " +"encourage product commercialization. Any BSD code can be sold or included " +"in proprietary products without any restrictions on the availability of your " +"code or your future behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:123 +msgid "" +"Do not confuse the new BSD license with \"public domain\". While an item in " +"the public domain is also free for all to use, it has no owner." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:125 +#, no-wrap +msgid "The origins of the GPL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:129 +msgid "" +"While the future of Unix had been so muddled in the late 1980s and early " +"1990s, the GPL, another development with important licensing considerations, " +"reached fruition." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:138 +msgid "" +"Richard Stallman, the developer of Emacs, was a member of the staff at MIT " +"when his lab switched from home-grown to proprietary systems. Stallman " +"became upset when he found that he could not legally add minor improvements " +"to the system. (Many of Stallman's co-workers had left to form two " +"companies based on software developed at MIT and licensed by MIT; there " +"appears to have been disagreement over access to the source code for this " +"software). Stallman devised an alternative to the commercial software " +"license and called it the GPL, or \"GNU Public License\". He also started a " +"non-profit foundation, the http://www.fsf.org[Free Software Foundation] " +"(FSF), which intended to develop an entire operating system, including all " +"associated software, that would not be subject to proprietary licensing. " +"This system was called GNU, for \"GNU is Not Unix\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:143 +msgid "" +"The GPL was designed to be the antithesis of the standard proprietary " +"license. To this end, any modifications that were made to a GPL program " +"were required to be given back to the GPL community (by requiring that the " +"source of the program be available to the user) and any program that used or " +"linked to GPL code was required to be under the GPL. The GPL was intended " +"to keep software from becoming proprietary. As the last paragraph of the " +"GPL states:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:145 +msgid "" +"\"This General Public License does not permit incorporating your program " +"into proprietary programs.\"<<one>>" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:147 +msgid "" +"The http://www.opensource.org/licenses/gpl-license.php[GPL] is a complex " +"license so here are some rules of thumb when using the GPL:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:149 +msgid "" +"you can charge as much as you want for distributing, supporting, or " +"documenting the software, but you cannot sell the software itself." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:150 +msgid "" +"the rule-of-thumb states that if GPL source is required for a program to " +"compile, the program must be under the GPL. Linking statically to a GPL " +"library requires a program to be under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:151 +msgid "" +"the GPL requires that any patents associated with GPLed software must be " +"licensed for everyone's free use." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:152 +msgid "" +"simply aggregating software together, as when multiple programs are put on " +"one disk, does not count as including GPLed programs in non-GPLed programs." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:153 +msgid "" +"output of a program does not count as a derivative work. This enables the " +"gcc compiler to be used in commercial environments without legal problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:154 +msgid "" +"since the Linux kernel is under the GPL, any code statically linked with the " +"Linux kernel must be GPLed. This requirement can be circumvented by " +"dynamically linking loadable kernel modules. This permits companies to " +"distribute binary drivers, but often has the disadvantage that they will " +"only work for particular versions of the Linux kernel." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:157 +msgid "" +"Due in part to its complexity, in many parts of the world today the " +"legalities of the GPL are being ignored in regard to Linux and related " +"software. The long-term ramifications of this are unclear." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:159 +#, no-wrap +msgid "The origins of Linux and the LGPL" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:164 +msgid "" +"While the commercial Unix wars raged, the Linux kernel was developed as a PC " +"Unix clone. Linus Torvalds credits the existence of the GNU C compiler and " +"the associated GNU tools for the existence of Linux. He put the Linux " +"kernel under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:173 +msgid "" +"Remember that the GPL requires anything that statically links to any code " +"under the GPL also be placed under the GPL. The source for this code must " +"thus be made available to the user of the program. Dynamic linking, " +"however, is not considered a violation of the GPL. Pressure to put " +"proprietary applications on Linux became overwhelming. Such applications " +"often must link with system libraries. This resulted in a modified version " +"of the GPL called the http://www.opensource.org/licenses/lgpl-license." +"php[LGPL] (\"Library\", since renamed to \"Lesser\", GPL). The LGPL allows " +"proprietary code to be linked to the GNU C library, glibc. You do not have " +"to release the source code which has been dynamically linked to an LGPLed " +"library." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:177 +msgid "" +"If you statically link an application with glibc, such as is often required " +"in embedded systems, you cannot keep your application proprietary, that is, " +"the source must be released. Both the GPL and LGPL require any " +"modifications to the code directly under the license to be released." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:179 +#, no-wrap +msgid "Open Source licenses and the Orphaning Problem" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:184 +msgid "" +"One of the serious problems associated with proprietary software is known as " +"\"orphaning\". This occurs when a single business failure or change in a " +"product strategy causes a huge pyramid of dependent systems and companies to " +"fail for reasons beyond their control. Decades of experience have shown " +"that the momentary size or success of a software supplier is no guarantee " +"that their software will remain available, as current market conditions and " +"strategies can change rapidly." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:186 +msgid "" +"The GPL attempts to prevent orphaning by severing the link to proprietary " +"intellectual property." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:191 +msgid "" +"A BSD license gives a small company the equivalent of software-in-escrow " +"without any legal complications or costs. If a BSD-licensed program becomes " +"orphaned, a company can simply take over, in a proprietary manner, the " +"program on which they are dependent. An even better situation occurs when a " +"BSD code-base is maintained by a small informal consortium, since the " +"development process is not dependent on the survival of a single company or " +"product line. The survivability of the development team when they are " +"mentally in the zone is much more important than simple physical " +"availability of the source code." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:193 +#, no-wrap +msgid "What a license cannot do" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:197 +msgid "" +"No license can guarantee future software availability. Although a copyright " +"holder can traditionally change the terms of a copyright at anytime, the " +"presumption in the BSD community is that such an attempt simply causes the " +"source to fork." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:203 +msgid "" +"The GPL explicitly disallows revoking the license. It has occurred, " +"however, that a company (Mattel) purchased a GPL copyright (cphack), revoked " +"the entire copyright, went to court, and prevailed <<two>>. That is, they " +"legally revoked the entire distribution and all derivative works based on " +"the copyright. Whether this could happen with a larger and more dispersed " +"distribution is an open question; there is also some confusion regarding " +"whether the software was really under the GPL." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:208 +msgid "" +"In another example, Red Hat purchased Cygnus, an engineering company that " +"had taken over development of the FSF compiler tools. Cygnus was able to do " +"so because they had developed a business model in which they sold support " +"for GNU software. This enabled them to employ some 50 engineers and drive " +"the direction of the programs by contributing the preponderance of " +"modifications. As Donald Rosenberg states \"projects using licenses like " +"the GPL...live under constant threat of having someone take over the project " +"by producing a better version of the code and doing it faster than the " +"original owners.\" <<three>>" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:210 +#, no-wrap +msgid "GPL Advantages and Disadvantages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:214 +msgid "" +"A common reason to use the GPL is when modifying or extending the gcc " +"compiler. This is particularly apt when working with one-off specialty CPUs " +"in environments where all software costs are likely to be considered " +"overhead, with minimal expectations that others will use the resulting " +"compiler." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:217 +msgid "" +"The GPL is also attractive to small companies selling CDs in an environment " +"where \"buy-low, sell-high\" may still give the end-user a very inexpensive " +"product. It is also attractive to companies that expect to survive by " +"providing various forms of technical support, including documentation, for " +"the GPLed intellectual property world." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:220 +msgid "" +"A less publicized and unintended use of the GPL is that it is very favorable " +"to large companies that want to undercut software companies. In other " +"words, the GPL is well suited for use as a marketing weapon, potentially " +"reducing overall economic benefit and contributing to monopolistic behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:223 +msgid "" +"The GPL can present a real problem for those wishing to commercialize and " +"profit from software. For example, the GPL adds to the difficulty a " +"graduate student will have in directly forming a company to commercialize " +"his research results, or the difficulty a student will have in joining a " +"company on the assumption that a promising research project will be " +"commercialized." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:228 +msgid "" +"For those who must work with statically-linked implementations of multiple " +"software standards, the GPL is often a poor license, because it precludes " +"using proprietary implementations of the standards. The GPL thus minimizes " +"the number of programs that can be built using a GPLed standard. The GPL " +"was intended to not provide a mechanism to develop a standard on which one " +"engineers proprietary products. (This does not apply to Linux applications " +"because they do not statically link, rather they use a trap-based API.)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:232 +msgid "" +"The GPL attempts to make programmers contribute to an evolving suite of " +"programs, then to compete in the distribution and support of this suite. " +"This situation is unrealistic for many required core system standards, which " +"may be applied in widely varying environments which require commercial " +"customization or integration with legacy standards under existing (non-GPL) " +"licenses. Real-time systems are often statically linked, so the GPL and " +"LGPL are definitely considered potential problems by many embedded systems " +"companies." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:235 +msgid "" +"The GPL is an attempt to keep efforts, regardless of demand, at the research " +"and development stages. This maximizes the benefits to researchers and " +"developers, at an unknown cost to those who would benefit from wider " +"distribution." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:239 +msgid "" +"The GPL was designed to keep research results from transitioning to " +"proprietary products. This step is often assumed to be the last step in the " +"traditional technology transfer pipeline and it is usually difficult enough " +"under the best of circumstances; the GPL was intended to make it impossible." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:241 +#, no-wrap +msgid "BSD Advantages" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:244 +msgid "" +"A BSD style license is a good choice for long duration research or other " +"projects that need a development environment that:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:246 +msgid "has near zero cost" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:247 +msgid "will evolve over a long period of time" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:248 +msgid "" +"permits anyone to retain the option of commercializing final results with " +"minimal legal issues." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:250 +msgid "" +"This final consideration may often be the dominant one, as it was when the " +"Apache project decided upon its license:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:254 +msgid "" +"\"This type of license is ideal for promoting the use of a reference body of " +"code that implements a protocol for common service. This is another reason " +"why we choose it for the Apache group - many of us wanted to see HTTP " +"survive and become a true multiparty standard, and would not have minded in " +"the slightest if Microsoft or Netscape choose to incorporate our HTTP engine " +"or any other component of our code into their products, if it helped further " +"the goal of keeping HTTP common... All this means that, strategically " +"speaking, the project needs to maintain sufficient momentum, and that " +"participants realize greater value by contributing their code to the " +"project, even code that would have had value if kept proprietary.\"" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:258 +msgid "" +"Developers tend to find the BSD license attractive as it keeps legal issues " +"out of the way and lets them do whatever they want with the code. In " +"contrast, those who expect primarily to use a system rather than program it, " +"or expect others to evolve the code, or who do not expect to make a living " +"from their work associated with the system (such as government employees), " +"find the GPL attractive, because it forces code developed by others to be " +"given to them and keeps their employer from retaining copyright and thus " +"potentially \"burying\" or orphaning the software. If you want to force " +"your competitors to help you, the GPL is attractive." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:265 +msgid "" +"A BSD license is not simply a gift. The question \"why should we help our " +"competitors or let them steal our work?\" comes up often in relation to a " +"BSD license. Under a BSD license, if one company came to dominate a product " +"niche that others considered strategic, the other companies can, with " +"minimal effort, form a mini-consortium aimed at reestablishing parity by " +"contributing to a competitive BSD variant that increases market competition " +"and fairness. This permits each company to believe that it will be able to " +"profit from some advantage it can provide, while also contributing to " +"economic flexibility and efficiency. The more rapidly and easily the " +"cooperating members can do this, the more successful they will be. A BSD " +"license is essentially a minimally complicated license that enables such " +"behavior." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:268 +msgid "" +"A key effect of the GPL, making a complete and competitive Open Source " +"system widely available at cost of media, is a reasonable goal. A BSD style " +"license, in conjunction with ad-hoc-consortiums of individuals, can achieve " +"this goal without destroying the economic assumptions built around the " +"deployment-end of the technology transfer pipeline." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:270 +#, no-wrap +msgid "Specific Recommendations for using a BSD license" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:275 +msgid "" +"The BSD license is preferable for transferring research results in a way " +"that will widely be deployed and most benefit an economy. As such, research " +"funding agencies, such as the NSF, ONR and DARPA, should encourage in the " +"earliest phases of funded research projects, the adoption of BSD style " +"licenses for software, data, results, and open hardware. They should also " +"encourage formation of standards based around implemented Open Source " +"systems and ongoing Open Source projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:277 +msgid "" +"Government policy should minimize the costs and difficulties in moving from " +"research to deployment. When possible, grants should require results to be " +"available under a commercialization friendly BSD style license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:278 +msgid "" +"In many cases, the long-term results of a BSD style license more accurately " +"reflect the goals proclaimed in the research charter of universities than " +"what occurs when results are copyrighted or patented and subject to " +"proprietary university licensing. Anecdotal evidence exists that " +"universities are financially better rewarded in the long run by releasing " +"research results and then appealing to donations from commercially " +"successful alumni." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:279 +msgid "" +"Companies have long recognized that the creation of de facto standards is a " +"key marketing technique. The BSD license serves this role well, if a company " +"really has a unique advantage in evolving the system. The license is legally " +"attractive to the widest audience while the company's expertise ensures " +"their control. There are times when the GPL may be the appropriate vehicle " +"for an attempt to create such a standard, especially when attempting to " +"undermine or co-opt others. The GPL, however, penalizes the evolution of " +"that standard, because it promotes a suite rather than a commercially " +"applicable standard. Use of such a suite constantly raises commercialization " +"and legal issues. It may not be possible to mix standards when some are " +"under the GPL and others are not. A true technical standard should not " +"mandate exclusion of other standards for non-technical reasons." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:280 +msgid "" +"Companies interested in promoting an evolving standard, which can become the " +"core of other companies' commercial products, should be wary of the GPL. " +"Regardless of the license used, the resulting software will usually devolve " +"to whoever actually makes the majority of the engineering changes and most " +"understands the state of the system. The GPL simply adds more legal friction " +"to the result." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:281 +msgid "" +"Large companies, in which Open Source code is developed, should be aware " +"that programmers appreciate Open Source because it leaves the software " +"available to the employee when they change employers. Some companies " +"encourage this behavior as an employment perk, especially when the software " +"involved is not directly strategic. It is, in effect, a front-loaded " +"retirement benefit with potential lost opportunity costs but no direct " +"costs. Encouraging employees to work for peer acclaim outside the company is " +"a cheap portable benefit a company can sometimes provide with near zero " +"downside." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:282 +msgid "" +"Small companies with software projects vulnerable to orphaning should " +"attempt to use the BSD license when possible. Companies of all sizes should " +"consider forming such Open Source projects when it is to their mutual " +"advantage to maintain the minimal legal and organization overheads " +"associated with a true BSD-style Open Source project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:283 +msgid "" +"Non-profits should participate in Open Source projects when possible. To " +"minimize software engineering problems, such as mixing code under different " +"licenses, BSD-style licenses should be encouraged. Being leery of the GPL " +"should particularly be the case with non-profits that interact with the " +"developing world. In some locales where application of law becomes a costly " +"exercise, the simplicity of the new BSD license, as compared to the GPL, may " +"be of considerable advantage." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:285 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:290 +msgid "" +"In contrast to the GPL, which is designed to prevent the proprietary " +"commercialization of Open Source code, the BSD license places minimal " +"restrictions on future behavior. This allows BSD code to remain Open Source " +"or become integrated into commercial solutions, as a project's or company's " +"needs change. In other words, the BSD license does not become a legal time-" +"bomb at any point in the development process." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:292 +msgid "" +"In addition, since the BSD license does not come with the legal complexity " +"of the GPL or LGPL licenses, it allows developers and companies to spend " +"their time creating and promoting good code rather than worrying if that " +"code violates licensing." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:295 +#, no-wrap +msgid "Bibliographical References" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:298 +msgid "[[[one,1]]] http://www.gnu.org/licenses/gpl.html" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:300 +msgid "" +"[[[two,2]]] http://archives.cnn.com/2000/TECH/computing/03/28/cyberpatrol." +"mirrors/" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:302 +msgid "" +"[[[three,3]]] Open Source: the Unauthorized White Papers, Donald K. " +"Rosenberg, IDG Books, 2000. Quotes are from page 114, \"Effects of the GNU " +"GPL\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:304 +msgid "" +"[[[four,4]]] In the \"What License to Use?\" section of http://www.oreilly." +"com/catalog/opensources/book/brian.html" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/bsdl-gpl/_index.adoc:305 +msgid "" +"This whitepaper is a condensation of an original work available at http://" +"alumni.cse.ucsc.edu/~brucem/open_source_license.htm" +msgstr "" diff --git a/documentation/content/en/articles/building-products/_index.po b/documentation/content/en/articles/building-products/_index.po new file mode 100644 index 0000000000..f7405dcdc2 --- /dev/null +++ b/documentation/content/en/articles/building-products/_index.po @@ -0,0 +1,1102 @@ +# 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: 2022-02-01 09:21-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: YAML Front Matter: description +#: documentation/content/en/articles/building-products/_index.adoc:1 +#, no-wrap +msgid "How FreeBSD can help you build a better product" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/building-products/_index.adoc:1 +#: documentation/content/en/articles/building-products/_index.adoc:13 +#, no-wrap +msgid "Building Products with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:46 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:50 +msgid "" +"The FreeBSD project is a worldwide, volunteer based, and collaborative " +"project, which develops a portable and high-quality operating system. The " +"FreeBSD project distributes the source code for its product under a liberal " +"license, with the intention of encouraging the use of its code. " +"Collaborating with the FreeBSD project can help organizations reduce their " +"time to market, reduce engineering costs and improve their product quality." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:54 +msgid "" +"This article examines the issues in using FreeBSD code in appliances and " +"software products. It highlights the characteristics of FreeBSD that make " +"it an excellent substrate for product development. The article concludes by " +"suggesting a few \"best practices\" for organizations collaborating with the " +"FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:56 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:60 +#, no-wrap +msgid "Introduction" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:66 +msgid "" +"FreeBSD today is well-known as a high-performance server operating system. " +"It is deployed on millions of web servers and internet-facing hosts " +"worldwide. FreeBSD code also forms an integral part of many products, " +"ranging from appliances such as network routers, firewalls, and storage " +"devices, to personal computers. Portions of FreeBSD have also been used in " +"commercial shrink-wrapped software (see <<freebsd-intro>>)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:68 +msgid "" +"In this article we look at the link:https://www.FreeBSD.org/[FreeBSD " +"project] as a software engineering resource-as a collection of building " +"blocks and processes which you can use to build products." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:71 +msgid "" +"While FreeBSD's source is distributed freely to the public, to fully enjoy " +"the benefits of the project's work, organizations need to _collaborate_ with " +"the project. In subsequent sections of this article we discuss effective " +"means of collaboration with the project and the pitfalls that need to be " +"avoided while doing so." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:74 +#, no-wrap +msgid "" +"*Caveat Reader.* The author believes that the characteristics of the FreeBSD Project listed in this article were substantially true at the time the article was conceived and written (2005).\n" +"However, the reader should keep in mind that the practices and processes used by open-source communities can change over time, and that the information in this article should therefore be taken as indicative rather than normative.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:75 +#, no-wrap +msgid "Target Audience" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:78 +msgid "" +"This document would be of interest to the following broad groups of people:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:80 +msgid "" +"Decision makers in product companies looking at ways to improve their " +"product quality, reduce their time to market and lower engineering costs in " +"the long term." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:81 +msgid "" +"Technology consultants looking for best-practices in leveraging \"open-source" +"\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:82 +msgid "" +"Industry observers interested in understanding the dynamics of open-source " +"projects." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:83 +msgid "" +"Software developers seeking to use FreeBSD and looking for ways to " +"contribute back." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:84 +#, no-wrap +msgid "Article Goals" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:87 +msgid "After reading this article you should have:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:89 +msgid "" +"An understanding of the goals of the FreeBSD Project and its organizational " +"structure." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:90 +msgid "" +"An understanding of its development model and release engineering processes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:91 +msgid "" +"An understanding of how conventional corporate software development " +"processes differ from that used in the FreeBSD project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:92 +msgid "" +"Awareness of the communication channels used by the project and the level of " +"transparency you can expect." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:93 +msgid "" +"Awareness of optimal ways of working with the project-how best to reduce " +"engineering costs, improve time to market, manage security vulnerabilities, " +"and preserve future compatibility with your product as the FreeBSD project " +"evolves." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:94 +#, no-wrap +msgid "Article Structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:97 +msgid "The rest of the article is structured as follows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:99 +msgid "" +"<<freebsd-intro>> introduces the FreeBSD project, explores its " +"organizational structure, key technologies and release engineering processes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:100 +msgid "" +"<<freebsd-collaboration>> describes ways to collaborate with the FreeBSD " +"project. It examines common pitfalls encountered by corporates working with " +"voluntary projects like FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:101 +msgid "<<conclusion>> concludes." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:103 +#, no-wrap +msgid "FreeBSD as a set of building blocks" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:106 +msgid "FreeBSD makes an excellent foundation on which to build products:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:108 +msgid "" +"FreeBSD source code is distributed under a liberal BSD license facilitating " +"its adoption in commercial products <<Mon2005>> with minimum hassle." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:109 +msgid "" +"The FreeBSD project has excellent engineering practices that can be " +"leveraged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:110 +msgid "" +"The project offers exceptional transparency into its workings, allowing " +"organizations using its code to plan effectively for the future." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:111 +msgid "" +"The culture of the FreeBSD project, carried over from the Computer Science " +"Research Group at The University of California, Berkeley <<McKu1999-1>>, " +"fosters high-quality work. Some features in FreeBSD define the state of the " +"art." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:114 +msgid "" +"<<GoldGab2005>> examines the business reasons for using open-source in " +"greater detail. For organizations, the benefits of using FreeBSD components " +"in their products include a shorter time to market, lower development costs " +"and lower development risks." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:115 +#, no-wrap +msgid "Building with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:118 +msgid "Here are a few ways organizations have used FreeBSD:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:120 +msgid "As an upstream source for tested code for libraries and utilities." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:122 +msgid "" +"By being \"downstream\" of the project, organizations leverage the new " +"features, bug fixes and testing that the upstream code receives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:123 +msgid "" +"As an embedded OS (for example, for an OEM router and firewall device). In " +"this model, organizations use a customized FreeBSD kernel and application " +"program set along with a proprietary management layer for their device. OEMs " +"benefit from new hardware support being added by the FreeBSD project " +"upstream, and from the testing that the base system receives." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:125 +msgid "" +"FreeBSD ships with a self-hosting development environment that allows easy " +"creation of such configurations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:126 +msgid "" +"As a Unix compatible environment for the management functions of high-end " +"storage and networking devices, running on a separate processor \"blade\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:130 +msgid "" +"FreeBSD provides the tools for creating dedicated OS and application program " +"images. Its implementation of a BSD unix API is mature and tested. FreeBSD " +"can also provide a stable cross-development environment for the other " +"components of the high-end device." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:131 +msgid "" +"As a vehicle to get widespread testing and support from a worldwide team of " +"developers for non-critical \"intellectual property\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:135 +msgid "" +"In this model, organizations contribute useful infrastructural frameworks to " +"the FreeBSD project (for example, see man:netgraph[3]). The widespread " +"exposure that the code gets helps to quickly identify performance issues and " +"bugs. The involvement of top-notch developers also leads to useful " +"extensions to the infrastructure that the contributing organization also " +"benefits from." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:136 +msgid "" +"As a development environment supporting cross-development for embedded OSes " +"like http://www.rtems.com/[RTEMS] and http://ecos.sourceware.org/[eCOS]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:138 +msgid "" +"There are many full-fledged development environments in the {numports}-" +"strong collection of applications ported and packaged with FreeBSD." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:139 +msgid "" +"As a way to support a Unix-like API in an otherwise proprietary OS, " +"increasing its palatability for application developers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:143 +msgid "" +"Here parts of FreeBSD's kernel and application programs are \"ported\" to " +"run alongside other tasks in the proprietary OS. The availability of a " +"stable and well tested Unix(TM) API implementation can reduce the effort " +"needed to port popular applications to the proprietary OS. As FreeBSD ships " +"with high-quality documentation for its internals and has effective " +"vulnerability management and release engineering processes, the costs of " +"keeping up-to-date are kept low." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:145 +#, no-wrap +msgid "Technologies" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:149 +msgid "" +"There are a large number of technologies supported by the FreeBSD project. " +"A selection of these are listed below:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:151 +msgid "" +"A complete system that can cross-host itself for link:https://www.FreeBSD." +"org/platforms/[many architectures:]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:152 +msgid "" +"A modular symmetric multiprocessing capable kernel, with loadable kernel " +"modules and a flexible and easy to use configuration system." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:153 +msgid "" +"Support for emulation of Linux(TM) and SVR4 binaries at near machine speeds. " +"Support for binary Windows(TM) (NDIS) network drivers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:154 +msgid "" +"Libraries for many programming tasks: archivers, FTP and HTTP support, " +"thread support, in addition to a full POSIX(TM) like programming environment." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:155 +msgid "" +"Security features: Mandatory Access Control (man:mac[9]), jails (man:" +"jail[2]), ACLs, and in-kernel cryptographic device support." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:156 +msgid "" +"Networking features: firewall-ing, QoS management, high-performance TCP/IP " +"networking with support for many extensions." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:158 +msgid "" +"FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel " +"networking modules to be connected together in flexible ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:159 +msgid "" +"Support for storage technologies: Fibre Channel, SCSI, software and hardware " +"RAID, ATA and SATA." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:161 +msgid "" +"FreeBSD supports a number of filesystems, and its native UFS2 filesystem " +"supports soft updates, snapshots and very large filesystem sizes (16TB per " +"filesystem) <<McKu1999>>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:163 +msgid "" +"FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage " +"modules to be composed in flexible ways." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:164 +msgid "" +"Over {numports} ported applications, both commercial and open-source, " +"managed via the FreeBSD ports collection." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:165 +#, no-wrap +msgid "Organizational Structure" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:168 +msgid "FreeBSD's organizational structure is non-hierarchical." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:170 +msgid "" +"There are essentially two kinds of contributors to FreeBSD, general users of " +"FreeBSD, and developers with write access (known as _committers_ in the " +"jargon) to the source base." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:174 +msgid "" +"There are many thousands of contributors in the first group; the vast " +"majority of contributions to FreeBSD come from individuals in this group. " +"Commit rights (write access) to the repository are granted to individuals " +"who contribute consistently to the project. Commit rights come with " +"additional responsibilities, and new committers are assigned mentors to help " +"them learn the ropes." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:175 +#, no-wrap +msgid "FreeBSD Organization" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/building-products/_index.adoc:176 +#, no-wrap +msgid "freebsd-organization.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:179 +msgid "" +"Conflict resolution is performed by a nine member \"Core Team\" that is " +"elected from the group of committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:183 +msgid "" +"FreeBSD does not have \"corporate\" committers. Individual committers are " +"required to take responsibility for the changes they introduce to the code. " +"The extref:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> " +"documents the rules and responsibilities for committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:185 +msgid "FreeBSD's project model is examined in detail in <<Nik2005>>." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:186 +#, no-wrap +msgid "FreeBSD Release Engineering Processes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:190 +msgid "" +"FreeBSD's release engineering processes play a major role in ensuring that " +"its released versions are of a high quality. At any point of time, " +"FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, " +"FreeBSD Release Branches>>):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:192 +msgid "" +"New features and disruptive code enters on the development branch, also " +"known as the _-CURRENT_ branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:193 +msgid "" +"_-STABLE_ branches are code lines that are branched from HEAD at regular " +"intervals. Only tested code is allowed onto a -STABLE branch. New features " +"are allowed once they have been tested and stabilized in the -CURRENT branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:194 +msgid "" +"_-RELEASE_ branches are maintained by the FreeBSD security team. Only bug " +"fixes for critical issues are permitted onto -RELEASE branches." +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:196 +#, no-wrap +msgid "FreeBSD Release Branches" +msgstr "" + +#. type: Target for macro image +#: documentation/content/en/articles/building-products/_index.adoc:197 +#, no-wrap +msgid "freebsd-branches.png" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:200 +msgid "" +"Code lines are kept alive for as long as there is user and developer " +"interest in them." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:203 +msgid "" +"Machine architectures are grouped into \"tiers\"; _Tier 1_ architectures are " +"fully supported by the project's release engineering and security teams, " +"_Tier 2_ architectures are supported on a best effort basis, and " +"experimental architectures comprise _Tier 3_. The list of extref:" +"{committers-guide}[supported architectures, archs] is part of the FreeBSD " +"documentation collection." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:206 +msgid "" +"The release engineering team publishes a link:https://www.FreeBSD.org/releng/" +"[road map] for future releases of FreeBSD on the project's web site. The " +"dates laid down in the road map are not deadlines; FreeBSD is released when " +"its code and documentation are ready." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:208 +msgid "FreeBSD's release engineering processes are described in <<RelEngDoc>>." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:210 +#, no-wrap +msgid "Collaborating with FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:213 +msgid "" +"Open-source projects like FreeBSD offer finished code of a very high quality." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:218 +msgid "" +"While access to quality source code can reduce the cost of initial " +"development, in the long-term the costs of managing change begin to " +"dominate. As computing environments change over the years and new security " +"vulnerabilities are discovered, your product too needs to change and adapt. " +"Using open-source code is best viewed not as a one-off activity, but as an " +"__ongoing process__. The best projects to collaborate with are the ones " +"that are __live__; i.e., with an active community, clear goals and a " +"transparent working style." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:220 +msgid "" +"FreeBSD has an active developer community around it. At the time of writing " +"there are many thousands of contributors from every populated continent in " +"the world and over 300 individuals with write access to the project's source " +"repositories." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:221 +msgid "The goals of the FreeBSD project are <<Hub1994>>:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:223 +msgid "" +"To develop a high-quality operating system for popular computer hardware, " +"and," +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:224 +msgid "To make our work available to all under a liberal license." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:226 +msgid "" +"FreeBSD enjoys an open and transparent working culture. Nearly all " +"discussion in the project happens by email, on link:https://lists.freebsd." +"org/[public mailing lists] that are also archived for posterity. The " +"project's policies are link:https://www.FreeBSD.org/internal/policies/" +"[documented] and maintained under revision control. Participation in the " +"project is open to all." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:228 +#, no-wrap +msgid "Understanding FreeBSD culture" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:231 +msgid "" +"To be able to work effectively with the FreeBSD project, you need to " +"understand the project's culture." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:234 +msgid "" +"Volunteer driven projects operate under different rules than for-profit " +"corporates. A common mistake that companies make when venturing into the " +"open-source world is that of underplaying these differences." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:236 +#, no-wrap +msgid "*Motivation.* Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, \"elegance is never optional\"<<Nor1993>>.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:238 +#, no-wrap +msgid "*The Long Term View.* FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:240 +msgid "" +"The project values long-term perspectives <<Nor2001>>. A frequent acronym " +"encountered in the project is DTRT, which stands for \"Do The Right Thing\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:243 +#, no-wrap +msgid "" +"*Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.\n" +"At another level, the same notation is used for communication of intent between two programmers.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:247 +msgid "" +"Formal specifications and design documents are seldom used in the project. " +"Clear and well-written code and well-written change logs (<<fig-change-log, " +"A sample change log entry>>) are used in their place. FreeBSD development " +"happens by \"rough consensus and running code\"<<Carp1996>>." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:253 +#, no-wrap +msgid "" +"r151864 | bde | 2005-10-29 09:34:50 -0700 (Sat, 29 Oct 2005) | 13 lines\n" +"Changed paths:\n" +" M /head/lib/msun/src/e_rem_pio2f.c\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:263 +#, no-wrap +msgid "" +"Use double precision to simplify and optimize arg reduction for small\n" +"and medium size args too: instead of conditionally subtracting a float\n" +"17+24, 17+17+24 or 17+17+17+24 bit approximation to pi/2, always\n" +"subtract a double 33+53 bit one. The float version is now closer to\n" +"the double version than to old versions of itself -- it uses the same\n" +"33+53 bit approximation as the simplest cases in the double version,\n" +"and where the float version had to switch to the slow general case at\n" +"|x| == 2^7*pi/2, it now switches at |x| == 2^19*pi/2 the same as the\n" +"double version.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:266 +#, no-wrap +msgid "" +"This speeds up arg reduction by a factor of 2 for |x| between 3*pi/4 and\n" +"2^7*pi/4, and by a factor of 7 for |x| between 2^7*pi/4 and 2^19*pi/4.\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:267 +#, no-wrap +msgid "A sample change log entry [[fig-change-log]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:270 +msgid "" +"Communication between programmers is enhanced by the use of a common coding " +"standard man:style[9]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:273 +#, no-wrap +msgid "" +"*Communication Channels.* FreeBSD's contributors are spread across the world.\n" +"Email (and to a lesser extent, IRC) is the preferred means of communication in the project.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/building-products/_index.adoc:274 +#, no-wrap +msgid "Best Practices for collaborating with the FreeBSD project" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:277 +msgid "" +"We now look at a few best practices for making the best use of FreeBSD in " +"product development." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:278 +#, no-wrap +msgid "Plan for the long term" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:281 +msgid "" +"Setup processes that help in tracking the development of FreeBSD. For " +"example:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:283 +#, no-wrap +msgid "*Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:287 +msgid "" +"<<fig-svn-blame, An annotated source listing generated using `svn blame`>> " +"shows a portion of an annotated listing of the file referenced by the change " +"log in <<fig-change-log, A sample change log entry>>. The ancestry of each " +"line of the source is clearly visible. Annotated listings showing the " +"history of every file that is part of FreeBSD are https://svnweb.freebsd.org/" +"[available on the web]." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:291 +#, no-wrap +msgid "#REV #WHO #DATE #TEXT\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/building-products/_index.adoc:305 +#, no-wrap +msgid "" +"176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) #include <sys/cdefs.h>\n" +"176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) __FBSDID(\"$FreeBSD$\");\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) \n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) /* __ieee754_rem_pio2f(x,y)\n" +" 8870 rgrimes 1995-05-29 22:51:47 -0700 (Mon, 29 May 1995) *\n" +"176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * return the remainder of x rem pi/2 in *y\n" +"176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * use double precision for everything except passing x\n" +"152535 bde 2005-11-16 18:20:04 -0800 (Wed, 16 Nov 2005) * use __kernel_rem_pio2() for large x\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) */\n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) \n" +"176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) #include <float.h>\n" +"176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) \n" +" 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) #include \"math.h\"\n" +msgstr "" + +#. type: Block title +#: documentation/content/en/articles/building-products/_index.adoc:306 +#, no-wrap +msgid "An annotated source listing generated using `svn blame` [[fig-svn-blame]]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:309 +#, no-wrap +msgid "*Use a gatekeeper.* Appoint a _gatekeeper_ to monitor FreeBSD development, to keep an eye out for changes that could potentially impact your products.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:312 +#, no-wrap +msgid "" +"*Report bugs upstream.* If you notice bug in the FreeBSD code that you are using, file a https://www.FreeBSD.org/support/bugreports/[bug report].\n" +"This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.\n" +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:312 +#, no-wrap +msgid "Leverage FreeBSD's release engineering efforts" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:315 +msgid "" +"Use code from a -STABLE development branch of FreeBSD. These development " +"branches are formally supported by FreeBSD's release engineering and " +"security teams and comprise of tested code." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:316 +#, no-wrap +msgid "Donate code to reduce costs" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:320 +msgid "" +"A major proportion of the costs associated with developing products is that " +"of doing maintenance. By donating non-critical code to the project, you " +"benefit by having your code see much wider exposure than it would otherwise " +"get. This in turn leads to more bugs and security vulnerabilities being " +"flushed out and performance anomalies being identified and fixed." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:321 +#, no-wrap +msgid "Get support effectively" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:326 +msgid "" +"For products with tight deadlines, it is recommended that you hire or enter " +"into a consulting agreement with a developer or firm with FreeBSD " +"experience. The {freebsd-jobs} is a useful communication channel to find " +"talent. The FreeBSD project maintains a link:https://www.FreeBSD.org/" +"commercial/consult_bycat/[gallery of consultants and consulting firms] " +"undertaking FreeBSD work. The http://www.bsdcertification.org/[BSD " +"Certification Group] offers certification for all the major BSD derived OSes." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:329 +msgid "" +"For less critical needs, you can ask for help on the link:https://lists." +"freebsd.org/[project mailing lists]. A useful guide to follow when asking " +"for help is given in <<Ray2004>>." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:329 +#, no-wrap +msgid "Publicize your involvement" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:331 +msgid "" +"You are not required to publicize your use of FreeBSD, but doing so helps " +"both your effort as well as that of the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:335 +msgid "" +"Letting the FreeBSD community know that your company uses FreeBSD helps " +"improve your chances of attracting high quality talent. A large roster of " +"support for FreeBSD also means more mind share for it among developers. " +"This in turn yields a healthier foundation for your future." +msgstr "" + +#. type: Labeled list +#: documentation/content/en/articles/building-products/_index.adoc:335 +#, no-wrap +msgid "Support FreeBSD developers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:341 +msgid "" +"Sometimes the most direct way to get a desired feature into FreeBSD is to " +"support a developer who is already looking at a related problem. Help can " +"range from hardware donations to direct financial assistance. In some " +"countries, donations to the FreeBSD project enjoy tax benefits. The project " +"has a dedicated link:https://www.FreeBSD.org/donations/[donations liaison] " +"to assist donors. The project also maintains a web page where developers " +"link:https://www.FreeBSD.org/donations/wantlist/[list their needs]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:343 +msgid "" +"As a policy the FreeBSD project extref:{contributors}[acknowledges] all " +"contributions received on its web site." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:345 +#, no-wrap +msgid "Conclusion" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:349 +msgid "" +"The FreeBSD project's goals are to create and give away the source code for " +"a high-quality operating system. By working with the FreeBSD project you " +"can reduce development costs and improve your time to market in a number of " +"product development scenarios." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:353 +msgid "" +"We examined the characteristics of the FreeBSD project that make it an " +"excellent choice for being part of an organization's product strategy. We " +"then looked at the prevailing culture of the project and examined effective " +"ways of interacting with its developers. The article concluded with a list " +"of best-practices that could help organizations collaborating with the " +"project." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/building-products/_index.adoc:357 +#, no-wrap +msgid "Bibliography" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:360 +msgid "" +"[[Carp1996]] [Carp1996] http://www.ietf.org/rfc/rfc1958.txt[The " +"Architectural Principles of the Internet] B. Carpenter. The Internet " +"Architecture Board.The Internet Architecture Board. Copyright(R) 1996." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:362 +msgid "" +"[[ComGuide]] [ComGuide] extref:{committers-guide}[Committer's Guide] The " +"FreeBSD Project. Copyright(R) 2005." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:364 +msgid "" +"[[GoldGab2005]] [GoldGab2005] http://dreamsongs.com/IHE/IHE.html[Innovation " +"Happens Elsewhere: Open Source as Business Strategy] Ron Goldman. Richard " +"Gabriel. Copyright(R) 2005. Morgan-Kaufmann." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:366 +msgid "" +"[[Hub1994]] [Hub1994] extref:{contributing}[Contributing to the FreeBSD " +"Project] Jordan Hubbard. Copyright(R) 1994-2005. The FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:368 +msgid "" +"[[McKu1999]] [McKu1999] http://www.usenix.org/publications/library/" +"proceedings/usenix99/mckusick.html[Soft Updates: A Technique for Eliminating " +"Most Synchronous Writes in the Fast Filesystem] Kirk McKusick. Gregory " +"Ganger. Copyright(R) 1999." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:370 +msgid "" +"[[McKu1999-1]] [McKu1999-1] http://www.oreilly.com/catalog/opensources/book/" +"kirkmck.html[Twenty Years of Berkeley Unix: From AT&T-Owned to Freely " +"Redistributable] Marshall Kirk McKusick. http://www.oreilly.com/catalog/" +"opensources/book/toc.html[Open Sources: Voices from the Open Source " +"Revolution] O'Reilly Inc.. Copyright(R) 1993." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:372 +msgid "" +"[[Mon2005]] [Mon2005] extref:{bsdl-gpl}[Why you should use a BSD style " +"license for your Open Source Project] Bruce Montague. The FreeBSD Project. " +"Copyright(R) 2005." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:374 +msgid "" +"[[Nik2005]] [Nik2005] extref:{dev-model}[A project model for the FreeBSD " +"Project] Niklas Saers. Copyright(R) 2005. The FreeBSD Project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:376 +msgid "" +"[[Nor1993]] [Nor1993] http://www.norvig.com/luv-slides.ps[Tutorial on Good " +"Lisp Programming Style] Peter Norvig. Kent Pitman. Copyright(R) 1993." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:378 +msgid "" +"[[Nor2001]] [Nor2001] http://www.norvig.com/21-days.html[Teach Yourself " +"Programming in Ten Years] Peter Norvig. Copyright(R) 2001." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:380 +msgid "" +"[[Ray2004]] [Ray2004] http://www.catb.org/~esr/faqs/smart-questions.html[How " +"to ask questions the smart way] Eric Steven Raymond. Copyright(R) 2004." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/building-products/_index.adoc:381 +msgid "" +"[[RelEngDoc]] [RelEngDoc] extref:{releng}[FreeBSD Release Engineering] " +"Murray Stokely. Copyright(R) 2001. The FreeBSD Project." +msgstr "" diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 2c2bfb86a9..612db2afb0 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2,9 +2,9 @@ title: Committer's Guide authors: - author: The FreeBSD Documentation Project -copyright: 1999-2021 The FreeBSD Documentation Project +copyright: 1999-2022 The FreeBSD Documentation Project description: Introductory information for FreeBSD committers -trademarks: ["freebsd", "coverity", "ibm", "intel", "general"] +trademarks: ["freebsd", "coverity", "git", "github", "gitlab", "ibm", "intel", "general"] weight: 25 tags: ["FreeBSD Committer's Guide", "Guide", "Community"] --- @@ -48,7 +48,7 @@ All new committers should read this document before they start, and existing com Almost all FreeBSD developers have commit rights to one or more repositories. However, a few developers do not, and some of the information here applies to them as well. -(For instance, some people only have rights to work with the Problem Report database). +(For instance, some people only have rights to work with the Problem Report database.) Please see <<non-committers>> for more information. This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works. @@ -77,19 +77,19 @@ toc::[] |`smtp.FreeBSD.org:587` (see also <<smtp-setup>>). |`_src/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/src.git` (see also <<git-getting-started-base-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/src.git` |`_doc/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/doc.git` (see also <<git-getting-started-doc-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/doc.git` |`_ports/_` Git Repository -|`ssh://git@gitrepo.FreeBSD.org/ports.git` (see also <<git-getting-started-ports-layout>>). +|`ssh://git@gitrepo.FreeBSD.org/ports.git` |_Internal Mailing Lists_ -|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on the `FreeBSD.org` cluster.) +|developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on `freefall.FreeBSD.org`.) |_Core Team monthly reports_ -|[.filename]#/home/core/public/monthly-reports# on the `FreeBSD.org` cluster. +|[.filename]#/home/core/public/reports# on the `FreeBSD.org` cluster. |_Ports Management Team monthly reports_ |[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster. @@ -111,7 +111,7 @@ Useful links: Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) standard are used by the FreeBSD project to authenticate committers. Messages carrying important information like public SSH keys can be signed with the OpenPGP key to prove that they are really from the committer. -See http://www.nostarch.com/pgp_ml.htm[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information. +See https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] for more information. [[pgpkeys-creating]] === Creating a Key @@ -177,7 +177,7 @@ Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o You need a Passphrase to protect your secret key. .... -<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2013-12). http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits[] describes the situation in more detail. +<.> 2048-bit keys with a three-year expiration provide adequate protection at present (2022-10). <.> A three year key lifespan is short enough to obsolete keys weakened by advancing computer power, but long enough to reduce key management problems. @@ -185,7 +185,7 @@ You need a Passphrase to protect your secret key. + After the email address is entered, a passphrase is requested. Methods of creating a secure passphrase are contentious. -Rather than suggest a single way, here are some links to sites that describe various methods: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[], http://en.wikipedia.org/wiki/Passphrase[]. +Rather than suggest a single way, here are some links to sites that describe various methods: https://world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/Passphrase[]. ==== Protect the private key and passphrase. @@ -266,7 +266,7 @@ Committers are encouraged to seek review for their work as part of the normal de === Policy for Committer Activity in Other Trees * All committers may modify [.filename]#src/share/misc/committers-*.dot#, [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and [.filename]#ports/astro/xearth/files#. -* doc committers may commit documentation changes to [.filename]#src# files, such as man pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. +* doc committers may commit documentation changes to [.filename]#src# files, such as manual pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. * Any committer may make changes to any other tree with an "Approved by" from a non-mentored committer with the appropriate bit. Mentored committers can provide a "Reviewed by" but not an "Approved by". * Committers can acquire an additional bit by the usual process of finding a mentor who will propose them to core, doceng, or portmgr, as appropriate. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of "Approved by" for some period. @@ -327,7 +327,7 @@ This primer is less ambitiously scoped than the old Subversion Primer, but shoul If you want to download FreeBSD, compile it from sources, and generally keep up to date that way, this primer is for you. It covers getting the sources, updating the sources, bisecting and touches briefly on how to cope with a few local changes. It covers the basics, and tries to give good pointers to more in-depth treatment for when the reader finds the basics insufficient. -Other sections of this guide cover more advanced topics related to contributing to the project. +Other sections of this guide cover more advanced topics related to contributing to the project. The goal of this section is to highlight those bits of Git needed to track sources. They assume a basic understanding of Git. @@ -338,6 +338,7 @@ There are many primers for Git on the web, but the https://git-scm.com/book/en/v This section describes the read-write access for committers to push the commits from developers or contributors. +[[git-mini-daily-use]] ===== Daily use * Clone the repository: @@ -385,7 +386,7 @@ freebsd https://git.freebsd.org/${repo}.git (fetch) freebsd git@gitrepo.freebsd.org:${repo}.git (push) .... + -Again, note that `gitrepo.freebsd.org` will be canonicalized to `repo.freebsd.org` in the future. +Again, note that `gitrepo.freebsd.org` has been canonicalized to `repo.freebsd.org`. * Install commit message template hook: + @@ -416,7 +417,7 @@ git worktree add -b admin ../${repo}-admin internal/admin .... For browsing `internal/admin` branch on web: -https://cgit.freebsd.org/${repo}/log/?h=internal/admin +`https://cgit.freebsd.org/${repo}/log/?h=internal/admin` For pushing, either specify the full refspec: @@ -425,13 +426,6 @@ For pushing, either specify the full refspec: git push freebsd HEAD:refs/internal/admin .... -Or set `push.default` to `freebsd` which will make `git push` to push the current branch back to its upstream by default, which is more suitable for our workflow: - -[source,shell] -.... -git config push.default freebsd -.... - ==== Keeping Current With The FreeBSD src Tree [[keeping_current]] First step: cloning a tree. @@ -440,13 +434,24 @@ There are two ways to download. Most people will want to do a deep clone of the repository. However, there are times when you may wish to do a shallow clone. -===== Branch names -The branch names in the new Git repository are similar to the old names. -For the stable branches, they are stable/X where X is the major release (like 11 or 12). -The main branch in the new repository is 'main'. -The main branch in the old GitHub mirror was 'master', but is now 'main'. -Both reflect the defaults of Git at the time they were created. -The 'main' branch is the default branch if you omit the '-b branch' or '--branch branch' options below. +===== Branch Names +FreeBSD-CURRENT uses the `main` branch. + +`main` is the default branch. + +For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`. + +For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` and `releng/13.2`. + +https://www.freebsd.org/releng/[] shows: + +* `main` and `stable/⋯` branches open +* `releng/⋯` branches, each of which is frozen when a release is tagged. + +Examples: + +* tag https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1] branch +* tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch. ===== Repositories Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources. @@ -461,12 +466,12 @@ It is the easiest to do. It also allows you to use Git's worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository. [source,shell] .... -% git clone -o freebsd $URL -b branch [dir] +% git clone -o freebsd $URL -b branch [<directory>] .... -is how you make a deep clone. -'branch' should be one of the branches listed in the previous section. -It is optional if it is the main branch. -'dir' is an optional directory to place it in (the default will be the name of the repo you are cloning (src, doc, etc)). +-- will create a deep clone. +`branch` should be one of the branches listed in the previous section. +If no `branch` is given: the default (`main`) will be used. +If no `<directory>` is given: the name of the new directory will match the name of the repo ([.filename]#doc#, [.filename]#ports# or [.filename]#src#). You will want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. It is the easiest to keep up to date as well. @@ -487,7 +492,7 @@ However, see below for a significant limitation of this approach. This clones the repository, but only has the most recent version in the repository. The rest of the history is not downloaded. -Should you change your mind later, you can do 'git fetch --unshallow' to get the old history. +Should you change your mind later, you can do `git fetch --unshallow` to get the old history. [WARNING] ==== @@ -522,15 +527,15 @@ This pulls in all the revisions since your last update. .... will update the tree. In Git, a 'fast forward' merge is one that only needs to set a new branch pointer and doesn't need to re-create the commits. -By always doing a 'fast forward' merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree. +By always doing a fast forward merge/pull, you'll ensure that you have an exact copy of the FreeBSD tree. This will be important if you want to maintain local patches. See below for how to manage local changes. -The simplest is to use --autostash on the 'git pull' command, but more sophisticated options are available. +The simplest is to use `--autostash` on the `git pull` command, but more sophisticated options are available. ==== Selecting a Specific Version -In Git, the 'git checkout' checks out both branches and specific versions. +In Git, `git checkout` checks out both branches and specific versions. Git's versions are the long hashes rather than a sequential number. When you checkout a specific version, just specify the hash you want on the command line (the git log command can help you decide which hash you might want): @@ -564,28 +569,28 @@ Sometimes, things go wrong. The last version worked, but the one you just updated to does not. A developer may ask you to bisect the problem to track down which commit caused the regression. -Git makes bisecting changes easy with a powerful 'git bisect' command. +Git makes bisecting changes easy with a powerful `git bisect` command. Here's a brief outline of how to use it. For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details. The man git-bisect page is good at describing what can go wrong, what to do when versions won't build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here. `git bisect start --first-parent` will start the bisection process. Next, you need to tell a range to go through. -'git bisect good XXXXXX' will tell it the working version and 'git bisect bad XXXXX' will tell it the bad version. +`git bisect good XXXXXX` will tell it the working version and `git bisect bad XXXXX` will tell it the bad version. The bad version will almost always be HEAD (a special tag for what you have checked out). The good version will be the last one you checked out. The `--first-parent` argument is necessary so that subsequent `git bisect` commands do not try to check out a vendor branch which lacks the full FreeBSD source tree. [TIP] ==== -If you want to know the last version you checked out, you should use 'git reflog': +If you want to know the last version you checked out, you should use `git reflog`: [source,shell] .... 5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main ... .... -shows me moving the working tree to the main branch (a816...) and then updating from upstream (to 5ef0...). +shows me moving the working tree to the `main` branch (a816...) and then updating from upstream (to 5ef0...). In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. As you can see from the output, HEAD@{1} also often works, but isn't foolproof if you have done other things to your Git tree after updating, but before you discover the need to bisect. ==== @@ -602,11 +607,11 @@ Bisecting: 1722 revisions left to test after this (roughly 11 steps) .... You would then build/install that version. -If it's good you'd type 'git bisect good' otherwise 'git bisect bad'. -If the version doesn't compile, type 'git bisect skip'. +If it's good you'd type `git bisect good` otherwise `git bisect bad`. +If the version doesn't compile, type `git bisect skip`. You will get a similar message to the above after each step. When you are done, report the bad version to the developer (or fix the bug yourself and send a patch). -'git bisect reset' will end the process and return you back to where you started (usually tip of main). +`git bisect reset` will end the process and return you back to where you started (usually tip of `main`). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases. [[git-gpg-signing]] @@ -667,8 +672,8 @@ The cgit repository web interface for use with web browsers is at https://cgit.F The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview. -The 'current' branch is 'main' . -The quarterly branches are named 'yyyyQn' for year 'yyyy' and quarter 'n'. +The _latest_ branch is `main`. +The _quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'. [[port-commit-message-formats]] ===== Commit message formats @@ -709,16 +714,16 @@ However, if you have local changes, you can use the same tool to manage them as All changes that you have not pushed are local and can easily be modified (git rebase, discussed below does this). ===== Keeping local changes -The simplest way to keep local changes (especially trivial ones) is to use 'git stash'. -In its simplest form, you use 'git stash' to record the changes (which pushes them onto the stash stack). +The simplest way to keep local changes (especially trivial ones) is to use `git stash`. +In its simplest form, you use `git stash` to record the changes (which pushes them onto the stash stack). Most people use this to save changes before updating the tree as described above. -They then use 'git stash apply' to re-apply them to the tree. -The stash is a stack of changes that can be examined with 'git stash list'. +They then use `git stash apply` to re-apply them to the tree. +The stash is a stack of changes that can be examined with `git stash list`. The git-stash man page (https://git-scm.com/docs/git-stash) has all the details. This method is suitable when you have tiny tweaks to the tree. When you have anything non trivial, you'll likely be better off keeping a local branch and rebasing. -Stashing is also integrated with the 'git pull' command: just add '--autostash' to the command line. +Stashing is also integrated with the `git pull` command: just add `--autostash` to the command line. ===== Keeping a local branch [[keeping_a_local_branch]] @@ -729,7 +734,7 @@ Git also allows one to merge, along with the same problems. That's one way to manage the branch, but it's the least flexible. In addition to merging, Git supports the concept of 'rebasing' which avoids these issues. -The 'git rebase' command replays all the commits of a branch at a newer location on the parent branch. +The `git rebase` command replays all the commits of a branch at a newer location on the parent branch. We will cover the most common scenarios that arise using it. ====== Create a branch @@ -766,9 +771,10 @@ The commit will pop you into an editor to describe what you've done. Once you enter that, you have your own **local** branch in the Git repo. Build and install it like you normally would, following the directions in the handbook. Git differs from other version control systems in that you have to tell it explicitly which files to commit. -I have opted to do it on the commit command line, but you can also do it with 'git add' which many of the more in depth tutorials cover. +I have opted to do it on the commit command line, but you can also do it with `git add` which many of the more in depth tutorials cover. ====== Time to update + When it is time to bring in a new version, it is almost the same as w/o the branches. You would update like you would above, but there is one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. @@ -810,15 +816,14 @@ Could not apply 646e0f9cda11... no color ls which looks scary. If you bring up an editor, you will see it is a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted): [source,shell] -.... -<<<<<<< HEAD -#ifdef COLORLS_NEW -#include <terminfo.h> -======= -#undef COLORLS -#ifdef COLORLS -#include <termcap.h> ->>>>>>> 646e0f9cda11... no color ls + <<<<<<< HEAD + #ifdef COLORLS_NEW + #include <terminfo.h> + ======= + #undef COLORLS + #ifdef COLORLS + #include <termcap.h> + >>>>>>> 646e0f9cda11... no color ls .... The new code is first, and your code is second. The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes: @@ -843,7 +848,7 @@ If the commit message is still accurate, just exit the editor. If you get stuck during the rebase, do not panic. git rebase --abort will take you back to a clean slate. It is important, though, to start with an unmodified tree. -An aside: The above mentioned 'git reflog' comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick. +An aside: The above mentioned `git reflog` comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick. For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment. It is a good resource for issues that arise occasionally but are too obscure for this guide. @@ -859,7 +864,7 @@ If you have a deep clone, the following will suffice: If you have a local branch, though, there are one or two caveats. First, rebase will rewrite history, so you will likely want to do something to save it. Second, jumping branches tends to cause more conflicts. -If we pretend the example above was relative to stable/12, then to move to main, I'd suggest the following: +If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following: [source,shell] .... % git checkout no-color-ls @@ -869,50 +874,9 @@ If we pretend the example above was relative to stable/12, then to move to main, What the above does is checkout no-color-ls. Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. -Then you rebase onto the main branch. +Then you rebase onto the `main` branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will -replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a place holder name). - -===== Migrating from an existing Git clone -If you have work based on a previous Git conversion or a locally running git-svn conversion, migrating to new repository can encounter problems because Git has no knowledge about the connection between the two. - -When you have only a few local changes, the easiest way would be to cherry-pick those changes to the new base: -[source,shell] -.... -% git checkout main -% git cherry-pick old_branch..your_branch -.... -Or alternatively, do the same thing with rebase: -[source,shell] -.... -% git rebase --onto main master your_branch -.... - -If you do have a lot of changes, you would probably want to perform a merge instead. -The idea is to create a merge point that consolidates the history of the old_branch, and the new FreeBSD repository (main). - -You can find out by looking up the same commit that are found on both parents: -[source,shell] -.... -% git show old_branch -.... -You will see a commit message, now search for that in the new branch: -[source,shell] -.... -% git log --grep="commit message on old_branch" freebsd/main -.... -You would help locate the commit hash on the new main branch, create a helper branch (in the example we call it 'stage') from that hash: -[source,shell] -.... -% git checkout -b stage _hash_found_from_git_log_ -.... -Then perform a merge of the old branch: -[source,shell] -.... -% git merge -s ours -m "Mark old branch as merged" old_branch -.... -With that, it's possible to merge your work branch or the main branch in any order without problem. -Eventually, when you are ready to commit your work back to main, you can perform a rebase to main, or do a squash commit by combining everything into one commit. +replay them onto the `main` branch creating a new no-color-ls branch there (which is why I had you create a place holder name). [[mfc-with-git]] === MFC (Merge From Current) Procedures @@ -995,9 +959,9 @@ Once the MFC is complete, you can delete the temporary branch: ==== MFC a vendor import -Vendor imports are the only thing in the tree that creates a merge commit in the main line. +Vendor imports are the only thing in the tree that creates a merge commit in the `main` branch. Cherry picking merge commits into stable/XX presents an additional difficulty because there are two parents for a merge commit. -Generally, you'll want the first parent's diff since that's the diff to mainline (though there may be some exceptions). +Generally, you'll want the first parent's diff since that's the diff to `main` (though there may be some exceptions). [source,shell] .... @@ -1006,9 +970,9 @@ Generally, you'll want the first parent's diff since that's the diff to mainline is typically what you want. This will tell cherry-pick to apply the correct diff. -There are some, hopefully, rare cases where it's possible that the mainline was merged backwards by the conversion script. -Should that be the case (and we've not found any yet), you'd change the above to '-m 2' to pickup the proper parent. -Just do +There are some, hopefully, rare cases where it's possible that the `main` branch was merged backwards by the conversion script. +Should that be the case (and we've not found any yet), you'd change the above to `-m 2` to pickup the proper parent. +Just do: [source,shell] .... % git cherry-pick --abort @@ -1025,7 +989,7 @@ then the easiest way is to use `git reset --hard` like so: % git reset --hard freebsd/stable/12 .... though if you have some revs you want to keep, and others you don't, -using 'git rebase -i' is better. +using `git rebase -i` is better. ==== Considerations when MFCing @@ -1037,7 +1001,7 @@ When committing source commits to stable and releng branches, we have the follow With Subversion, we used the following practices to achieve these goals: -* Using 'MFC' and 'MFS' tags to mark commits that merged changes from another branch. +* Using `MFC` and `MFS` tags to mark commits that merged changes from another branch. * Squashing fixup commits into the main commit when merging a change. * Recording mergeinfo so that `svn mergeinfo --show-revs` worked. @@ -1052,17 +1016,8 @@ Instead, when this document refers to "merge commits", it means a commit origina Git provides some built-in support for this via the `git cherry` and `git log --cherry` commands. These commands compare the raw diffs of commits (but not other metadata such as log messages) to determine if two commits are identical. -This works well when each commit from head is landed as a single commit to a stable branch, but it falls over if multiple commits from main are squashed together as a single commit to a stable branch. - -There are a few options for resolving this: - -1. We could ban squashing of commits and instead require that committers stage all of the fixup / follow-up commits to stable into a single push. -This would still achieve the goal of stability in stable and releng branches since pushes are atomic and users doing a simple pull will never end up with a tree that has the main commit without the fixup(s). -`git bisect` is also able to cope with this model via `git bisect skip`. - -2. We could adopt a consistent style for describing MFCs and write our own tooling to wrap around `git cherry` to determine the list of eligible commits. -A simple approach here might be to use the syntax from `git cherry-pick -x`, but require that a squashed commit list all of the hashes (one line per hash) at the end of the commit message. -Developers could do this by using `git cherry-pick -x` of each individual commit into a branch and then use `git rebase` to squash the commits down into a single commit, but collecting the `-x` annotations at the end of the landed commit log. +This works well when each commit from `main` is landed as a single commit to a stable branch, but it falls over if multiple commits from `main` are squashed together as a single commit to a stable branch. +The project makes extensive use of `git cherry-pick -x` with all lines preserved to work around these difficulties and is working on automated tooling to take advantage of this. ==== Commit message standards ===== Marking MFCs @@ -1081,7 +1036,7 @@ Should it include the metadata from the original commit unchanged, or should it Historical practice has varied, though some of the variance is by field. For example, MFCs that are relevant to a PR generally include the PR field in the MFC so that MFC commits are included in the bug tracker's audit trail. Other fields are less clear. -For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the `main` commit with the landed commits. +For example, Phabricator shows the diff of the last commit tagged to a review, so including Phabricator URLs replaces the main commit with the landed commits. The list of reviewers is also not clear. If a reviewer has approved a change to `main`, does that mean they have approved the MFC commit? Is that true if it's identical code only, or with merely trivial rework? It's clearly not true for more extensive reworks. Even for identical code what if the commit doesn't conflict but introduces an ABI change? A reviewer may have ok'd a commit for `main` due to the ABI breakage but may not approve of merging the same commit as-is. @@ -1092,268 +1047,13 @@ This new metadata will have to be added via `git commit --amend` or similar afte We may also want to reserve some metadata fields in MFC commits such as Phabricator URLs for use by re@ in the future. Preserving existing metadata provides a very simple workflow. -Developers can just use `git cherry-pick -x` without having to edit the log message. +Developers use `git cherry-pick -x` without having to edit the log message. If instead we choose to adjust metadata in MFCs, developers will have to edit log messages explicitly via the use of `git cherry-pick --edit` or `git commit --amend`. However, as compared to svn, at least the existing commit message can be pre-populated and metadata fields can be added or removed without having to re-enter the entire commit message. The bottom line is that developers will likely need to curate their commit message for MFCs that are non-trivial. -==== Examples - -===== Merging a Single Subversion Commit - -This walks through the process of merging a commit to stable/12 that was originally committed to head in Subversion. -In this case, the original commit is r368685. - -The first step is to map the Subversion commit to a Git hash. -Once you have fetched refs/notes/commits, you can pass the revision number to `git log --grep`: - -[source,shell] -.... -% git log main --grep 368685 -commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 -Author: John Baldwin <jhb@FreeBSD.org> -Date: Wed Dec 16 00:11:30 2020 +0000 - - Use the 't' modifier to print a ptrdiff_t. - - Reviewed by: imp - Obtained from: CheriBSD - Sponsored by: DARPA - Differential Revision: https://reviews.freebsd.org/D27576 - -Notes: - svn path=/head/; revision=368685 -.... - -Next, MFC the commit to a `stable/12` checkout: - -[source,shell] -.... -git checkout stable/12 -git cherry-pick -x ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81 --edit -.... - -Git will invoke the editor. -Use this to remove the metadata that only applied to the original commit (Phabricator URL and Reviewed by). -After the editor saves the updated log message, Git completes the commit: - -[source,shell] -.... -[stable/12 3e3a548c4874] Use the 't' modifier to print a ptrdiff_t. - Date: Wed Dec 16 00:11:30 2020 +0000 - 1 file changed, 1 insertion(+), 1 deletion(-) -.... - -The contents of the MFCd commit can be examined via `git show`: - -[source,shell] -.... -% git show -commit 3e3a548c487450825679e4bd63d8d1a67fd8bd2d (HEAD -> stable/12) -Author: John Baldwin <jhb@FreeBSD.org> -Date: Wed Dec 16 00:11:30 2020 +0000 - - Use the 't' modifier to print a ptrdiff_t. - - Obtained from: CheriBSD - Sponsored by: DARPA - - (cherry picked from commit ce8395ecfda2c8e332a2adf9a9432c2e7f35ea81) - -diff --git a/sys/compat/linuxkpi/common/include/linux/printk.h b/sys/compat/linuxkpi/common/include/linux/printk.h -index 31802bdd2c99..e6510e9e9834 100644 ---- a/sys/compat/linuxkpi/common/include/linux/printk.h -+++ b/sys/compat/linuxkpi/common/include/linux/printk.h -@@ -68,7 +68,7 @@ print_hex_dump(const char *level, const char *prefix_str, - printf("[%p] ", buf); - break; - case DUMP_PREFIX_OFFSET: -- printf("[%p] ", (const char *)((const char *)buf - -+ printf("[%#tx] ", ((const char *)buf - - (const char *)buf_old)); - break; - default: -.... - -The MFC commit can now be published via `git push` - -[source,shell] -.... -% git push freebsd -Enumerating objects: 17, done. -Counting objects: 100% (17/17), done. -Delta compression using up to 4 threads -Compressing objects: 100% (7/7), done. -Writing objects: 100% (9/9), 817 bytes | 204.00 KiB/s, done. -Total 9 (delta 5), reused 1 (delta 1), pack-reused 0 -To gitrepo-dev.FreeBSD.org:src.git - 525bd9c9dda7..3e3a548c4874 stable/12 -> stable/12 -.... - -===== Merging a Single Subversion Commit with a Conflict - -This example is similar to the previous example except that the commit in question encounters a merge conflict. -In this case, the original commit is r368314. - -As above, the first step is to map the Subversion commit to a Git hash: - -[source,shell] -.... -% git log main --grep 368314 -commit 99963f5343a017e934e4d8ea2371a86789a46ff9 -Author: John Baldwin <jhb@FreeBSD.org> -Date: Thu Dec 3 22:01:13 2020 +0000 - - Don't transmit mbufs that aren't yet ready on TOE sockets. - - This includes mbufs waiting for data from sendfile() I/O requests, or - mbufs awaiting encryption for KTLS. - - Reviewed by: np - MFC after: 2 weeks - Sponsored by: Chelsio Communications - Differential Revision: https://reviews.freebsd.org/D27469 - -Notes: - svn path=/head/; revision=368314 -.... - -Next, MFC the commit to a `stable/12` checkout: - -[source,shell] -.... -% git checkout stable/12 -% git cherry-pick -x 99963f5343a017e934e4d8ea2371a86789a46ff9 --edit -Auto-merging sys/dev/cxgbe/tom/t4_cpl_io.c -CONFLICT (content): Merge conflict in sys/dev/cxgbe/tom/t4_cpl_io.c -warning: inexact rename detection was skipped due to too many files. -warning: you may want to set your merge.renamelimit variable to at least 7123 and retry the command. -error: could not apply 99963f5343a0... Don't transmit mbufs that aren't yet ready on TOE sockets. -hint: after resolving the conflicts, mark the corrected paths -hint: with 'git add <paths>' or 'git rm <paths>' -hint: and commit the result with 'git commit' -.... - -In this case, the commit encountered a merge conflict in sys/dev/cxge/tom/t4_cpl_io.c as kernel TLS is not present in stable/12. -Note that Git does not invoke an editor to adjust the commit message due to the conflict. -`git status` confirms that this file has merge conflicts: - -[source,shell] -.... -% git status -On branch stable/12 -Your branch is up to date with 'upstream/stable/12'. - -You are currently cherry-picking commit 99963f5343a0. - (fix conflicts and run "git cherry-pick --continue") - (use "git cherry-pick --skip" to skip this patch) - (use "git cherry-pick --abort" to cancel the cherry-pick operation) - -Unmerged paths: - (use "git add <file>..." to mark resolution) - both modified: sys/dev/cxgbe/tom/t4_cpl_io.c - -no changes added to commit (use "git add" and/or "git commit -a") -.... - -After editing the file to resolve the conflict, `git status` shows the conflict as resolved: - -[source,shell] -.... -% git status -On branch stable/12 -Your branch is up to date with 'upstream/stable/12'. - -You are currently cherry-picking commit 99963f5343a0. - (all conflicts fixed: run "git cherry-pick --continue") - (use "git cherry-pick --skip" to skip this patch) - (use "git cherry-pick --abort" to cancel the cherry-pick operation) - -Changes to be committed: - modified: sys/dev/cxgbe/tom/t4_cpl_io.c -.... - -The cherry-pick can now be completed: - -[source,shell] -.... -% git cherry-pick --continue -.... - -Since there was a merge conflict, Git invokes the editor to adjust the commit message. -Trim the metadata fields from the commit log from the original commit to head and save the updated log message. - -The contents of the MFC commit can be examined via `git show`: - -[source,shell] -.... -% git show -commit 525bd9c9dda7e7c7efad2d4570c7fd8e1a8ffabc (HEAD -> stable/12) -Author: John Baldwin <jhb@FreeBSD.org> -Date: Thu Dec 3 22:01:13 2020 +0000 - - Don't transmit mbufs that aren't yet ready on TOE sockets. - - This includes mbufs waiting for data from sendfile() I/O requests, or - mbufs awaiting encryption for KTLS. - - Sponsored by: Chelsio Communications - - (cherry picked from commit 99963f5343a017e934e4d8ea2371a86789a46ff9) - -diff --git a/sys/dev/cxgbe/tom/t4_cpl_io.c b/sys/dev/cxgbe/tom/t4_cpl_io.c -index 8e8c2b8639e6..43861f10b689 100644 ---- a/sys/dev/cxgbe/tom/t4_cpl_io.c -+++ b/sys/dev/cxgbe/tom/t4_cpl_io.c -@@ -746,6 +746,8 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - for (m = sndptr; m != NULL; m = m->m_next) { - int n; - -+ if ((m->m_flags & M_NOTAVAIL) != 0) -+ break; - if (IS_AIOTX_MBUF(m)) - n = sglist_count_vmpages(aiotx_mbuf_pages(m), - aiotx_mbuf_pgoff(m), m->m_len); -@@ -821,8 +823,9 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - - /* nothing to send */ - if (plen == 0) { -- KASSERT(m == NULL, -- ("%s: nothing to send, but m != NULL", __func__)); -+ KASSERT(m == NULL || (m->m_flags & M_NOTAVAIL) != 0, -+ ("%s: nothing to send, but m != NULL is ready", -+ __func__)); - break; - } - -@@ -910,7 +913,7 @@ t4_push_frames(struct adapter *sc, struct toepcb *toep, int drop) - toep->txsd_avail--; - - t4_l2t_send(sc, wr, toep->l2te); -- } while (m != NULL); -+ } while (m != NULL && (m->m_flags & M_NOTAVAIL) == 0); - - /* Send a FIN if requested, but only if there's no more data to send */ - if (m == NULL && toep->flags & TPF_SEND_FIN) -.... - -The MFC commit can now be published via `git push` - -[source,shell] -.... -git push freebsd -Enumerating objects: 13, done. -Counting objects: 100% (13/13), done. -Delta compression using up to 4 threads -Compressing objects: 100% (7/7), done. -Writing objects: 100% (7/7), 819 bytes | 117.00 KiB/s, done. -Total 7 (delta 6), reused 0 (delta 0), pack-reused 0 -To gitrepo.FreeBSD.org:src.git - f4d0bc6aa6b9..525bd9c9dda7 stable/12 -> stable/12 -.... - [[vendor-import-git]] === Vendor Imports with Git @@ -1448,56 +1148,85 @@ Because the current policy recommends against using merges, if the upstream Free Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a merge commit **as a merge commit**, so instead of that you would have to recreate the commit. -The easiest way to do this would be to create a side branch with the **contents** of the merged tree: +The following steps should be taken to easily recreate the merge commit as if `git rebase --merge-commits` worked properly: -[source,shell] -.... -% cd ../src -% git fetch freebsd -% git checkout -b merge_result -% git merge freebsd/main -.... +* cd to the top of the repo +* Create a side branch `XXX` with the **contents** of the merged tree. +* Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch. +** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. +** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed) +* checkout `main` +* create a branch `YYY` (allows for easier unwinding if things go wrong) +* Re-do the subtree merge +* Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it. +** The trailing `.` is important, as is being at the top level of the repo. +** Rather than switching branches to XXX, it splats the contents of XXX on top of the repo +* Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch). +* Make sure the branches are the same. +* Do whatever review you need, including having others check it out if you think that's needed. +* Push the commit, if you 'lost the race' again, just redo these steps again (see below for a recipe) +* Delete the branches once the commit is upstream. They are throw-a-way. -Typically, there would be no merge conflicts here (because developers tend to work on different components). -In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. - -Now, checkout `freebsd/main` again as `new_merge`, and redo the merge: +The commands one would use, following the above example of mtree, would be like so (the `#` starts a comment to help link commands to descriptions above): [source,shell] .... -% git checkout -b new_merge freebsd/main -% git subtree merge -P contrib/mtree vendor/NetBSD/mtree +% cd ../src # CD to top of tree +% git checkout -b XXX # create new throw-away XXX branch for merge +% git fetch freebsd # Get changes from upstream from upstream +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase +% git diff XXX YYY # Should be empty +% git show YYY # Should only have changes you want, and be a merge commit from vendor branch .... -Instead of resolving the conflicts, perform this instead: - +Note: if things go wrong with the commit, you can reset the `YYY` branch by reissuing the checkout command that created it with -B to start over: [source,shell] .... -% git checkout merge_result . +% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if starting over is just going to be easier .... -Which will overwrite the files with conflicts with the version found in `merge_result`. +==== Pushing the changes + +Once you think you have a set of changes that are good, you can push it to a fork off GitHub or GitLab for others to review. +One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. +While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. -Examine the tree against `merge_result` to make sure that you haven't missed deleted files: +After review, when you are sure it is a good change, you can push it to the FreeBSD repo: [source,shell] .... -% git diff merge_result +% git push freebsd YYY:main # put the commit on upstream's 'main' branch +% git branch -D XXX # Throw away the throw-a-way branches. +% git branch -D YYY .... -==== Pushing the changes +Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine. +If you use such names for other work, then you'll need to pick different names, or risk losing the other work. +There is nothing magic about these names. +Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above. +Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working. -Once you are sure that you have a set of deltas you think is good, you can push it to a fork off GitHub or GitLab for others to review. -One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. -While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. +==== How to redo things if need be -After review, when you are sure it is a good change, you can push it to the FreeBSD repo: +If you've tried to do the push in the previous section and it fails, then you should do the following to 'redo' things. +This sequence keeps the commit with the commit message always at XXX~1 to make committing easier. [source,shell] .... -% git push freebsd main +% git checkout -B XXX YYY # recreate that throw-away-branch XXX and switch to it +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase .... +Then go check it out as above and push as above when ready. + === Creating a new vendor branch There are a number of ways to create a new vendor branch. @@ -1593,7 +1322,7 @@ Here 'good' means: . All the right files, and none of the wrong ones, were merged into contrib/glorbnitz. . No other changes are in the tree. -. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD main line and any caveats. +. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats. . UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc. [NOTE] @@ -1602,90 +1331,6 @@ This hasn't connected `glorbnitz` to the build yet. How so do that is specific to the software being imported and is beyond the scope of this tutorial. ==== -=== FreeBSD Src Committer Transition Guide - -This section is designed to walk people through the conversion process from Subversion to Git, written from the source committer's point of view. - -==== Migrating from a Subversion tree - -This section will cover a couple of common scenarios for migrating from using the FreeBSD Subversion repo to the FreeBSD source Git repo. -The FreeBSD Git conversion is still in beta status, so some minor things may change between this and going into production. - -The first thing to do is install Git. Any version of Git will do, though the latest one in ports / packages generally will be good. -Either build it from ports, or install it using pkg (though some folks might use `su` or `doas` instead of `sudo`): - -[source,shell] -.... -% sudo pkg install git -.... - -===== No staged changes migration - -If you have no changes pending, the migration is straightforward. -In this, you abandon the Subversion tree and clone the Git repository. -It's likely best to retain your Subversion tree, in case there's something you've forgotten about there. -First, let's clone the repository: - -[source,shell] -.... -% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/src.git freebsd-src -.... - -will create a clone of the FreeBSD src repository into a subdirectory called `freebsd-src` and include the 'notes' about the revisions. -We are currently mirroring the source repository to https://github.com/freebsd/freebsd-src.git as well. -https://github.com/freebsd/freebsd-legacy.git has the old GitHub mirror with the old hashes should you need that for your migration. -The GitHub `master` branch has been frozen. -As the default in Git has changed, we've shifted from `master` to `main`; the new repository uses `main`. -We also mirror the repository to GitLab at https://gitlab.com/FreeBSD/src.git . - -It's useful to have the old Subversion revisions available. -This data is stored using Git notes, but Git doesn't fetch those by default. -The --config and the argument above changed the default to fetch the notes. -If you've cloned the repository without this, or wish to add notes to a previously cloned repository, use the following commands: - -[source,shell] -.... -% git config --add remote.freebsd.fetch "+refs/notes/*:refs/notes/*" -% git fetch -.... - -At this point you have the src checked out into a Git tree, ready to do other things. - -===== But I have changes that I've not committed - -If you are migrating from a tree that has changes you've not yet committed to FreeBSD, you'll need to follow the steps from the previous section first, and then follow these. - -[source,shell] -.... -% cd path-to-svn-checkout-tree -% svn diff > /tmp/src.diff -% cd _mumble_/freebsd-src -% git checkout -b working -.... - -This will create a diff of your current changes. -The last command creates a branch called `working` though you can call it whatever you want. - -[source,shell] -.... -% git apply /tmp/src.diff -.... - -this will apply all your pending changes to the working tree. -This doesn't commit the change, so you'll need to make this permanent: - -[source,shell] -.... -% git add _files_ -% git commit -.... - -The last command will commit these changes to the branch. -The editor will prompt you for a commit message. -Enter one as if you were committing to FreeBSD. - -At this point, your work is preserved, and in the Git repository. - ===== Keeping current So, time passes. @@ -1694,7 +1339,7 @@ When you checkout `main` make sure that you have no diffs. It's a lot easier to commit those to a branch (or use `git stash`) before doing the following. If you are used to `git pull`, we strongly recommend using the `--ff-only` option, and further setting it as the default option. -Alternatively, `git pull --rebase` is useful if you have changes staged in the main branch. +Alternatively, `git pull --rebase` is useful if you have changes staged in the `main` branch. [source,shell] .... @@ -1723,7 +1368,7 @@ The longer form is also recommended. % git merge --ff-only freebsd/main .... -These commands reset your tree to the main branch, and then update it from where you pulled the tree from originally. +These commands reset your tree to the `main` branch, and then update it from where you pulled the tree from originally. It's important to switch to `main` before doing this so it moves forward. Now, it's time to move the changes forward: @@ -1760,9 +1405,9 @@ freefall% gen-gitconfig.sh on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH. -The below command merges the `working` branch into the upstream main line. +The below command merges the `working` branch into the upstream `main` branch. It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this. -This syntax pushes the `working` branch to main, moving the `main` branch forward. +This syntax pushes the `working` branch to `main`, moving the `main` branch forward. You will only be able to do this if this results in a linear change to `main` (e.g. no merges). [source,shell] @@ -1804,7 +1449,7 @@ Note: merging vendor branch commits will not work with this technique. ===== Finding the Subversion Revision -You'll need to make sure that you've fetched the notes (see the `No staged changes migration` section above for details. +You'll need to make sure that you've fetched the notes (see the <<git-mini-daily-use>> for details). Once you have these, notes will show up in the git log command like so: [source,shell] @@ -1822,51 +1467,6 @@ If you have a specific version in mind, you can use this construct: to find the specific revision. The hex number after 'commit' is the hash you can use to refer to this commit. -==== Migrating from GitHub fork - -Note: as of this writing, https://github.com/freebsd/freebsd-src is mirroring all official branches, along with a `master` branch which is the legacy svn2git result. -The `master` branch will not be updated anymore, and the link:https://github.com/freebsd/freebsd-src/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf[last commit] contains the instructions for migrating to the new `main` branch. -We'll retain the `master` branch for a certain time, but in the future it will only be kept in the link:https://github.com/freebsd/freebsd-legacy[freebsd-legacy] repository. -In addition, link:https://github.com/freebsd/git_conv/wiki/Migrating-merge-based-project-from-legacy-git-tree[this article] has an earlier version of the last commit instructions that may be helpful. - -When migrating branches from a GitHub fork from the old GitHub mirror to the official repo, the process is straight forward. -This assumes that you have a `freebsd` upstream pointing to GitHub, adjust if necessary. -This also assumes a clean tree before starting... - -===== Add the new `freebsd` upstream repository: - -[source,shell] -.... -% git remote add freebsd https://git.freebsd.org/src.git -% git fetch freebsd -% git checkout --track freebsd/main -.... - -===== Rebase all your WIP branches. - -For each branch FOO, do the following after fetching the `freebsd` sources and creating a local `main` branch with the above checkout: - -[source,shell] -.... -% git rebase -i freebsd/master FOO --onto main -.... - -And you'll now be tracking the official repository. -You can then follow the `Keeping Current` section above to stay up to date. - -If you need to then commit work to FreeBSD, you can do so following the `Time to push changes upstream` instructions. -You'll need to do the following once to update the push URL if you are a FreeBSD committer: - -[source,shell] -.... -% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git -.... - -(note that gitrepo.freebsd.org will be change to repo.freebsd.org in the future.) - -You will also need to add `freebsd` as the location to push to. -The author recommends that your upstream GitHub repository remain the default push location so that you only push things into FreeBSD you intend to by making it explicit. - [[git-faq]] === Git FAQ @@ -1926,9 +1526,9 @@ Here's https://adventurist.me/posts/00296[a good writeup] that goes into more de ==== Developers -===== Ooops! I committed to `main` instead of a branch. +===== Ooops! I committed to `main`, instead of another branch. -**Q:** From time to time, I goof up and commit to main instead of to a branch. What do I do? +**Q:** From time to time, I goof up and mistakenly commit to the `main` branch. What do I do? **A:** First, don't panic. @@ -1969,7 +1569,7 @@ cherry-pick it over. **Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason? **A:** The same technique above also works if you are wanting to 'land' parts of the branch you are working on into `main` before the rest of the branch is ready (say you noticed an unrelated typo, or fixed an incidental bug). -You can cherry pick those changes into main, then push to the parent repository. +You can cherry pick those changes into `main`, then push to the parent repository. Once you've done that, cleanup couldn't be simpler: just `git rebase -i`. Git will notice you've done this and skip the common changes automatically (even if you had to change the commit message or tweak the commit slightly). There's no need to switch back to wilma to adjust it: just rebase! @@ -2046,8 +1646,8 @@ You can also stack: .... and you are ready to try again. -The 'checkout -B' with the hash combines checking out and creating a branch for it. -The -B instead of -b forces the movement of a pre-existing branch. +The `checkout -B` with the hash combines checking out and creating a branch for it. +The `-B` instead of `-b` forces the movement of a pre-existing branch. Either way works, which is what's great (and awful) about Git. One reason I tend to use `git checkout -B xxxx hash` instead of checking out the hash, and then creating / moving the branch is purely to avoid the slightly distressing message about detached heads: @@ -2074,7 +1674,7 @@ this produces the same effect, but I have to read a lot more and severed heads a ===== Ooops! I did a `git pull` and it created a merge commit, what do I do? -**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on the mainline. +**Q:** I was on autopilot and did a `git pull` for my development tree and that created a merge commit on `main`. How do I recover? **A:** This can happen when you invoke the pull with your development branch checked out. @@ -2224,7 +1824,7 @@ However, there are two disadvantages to this if you want to use it for anything First, this is a 'bare repository' which has the repository database, but no checked out worktree. This is great for mirroring, but terrible for day to day work. -There's a number of ways around this with 'git worktree': +There's a number of ways around this with `git worktree`: [source,shell] .... @@ -2261,7 +1861,7 @@ To setup your repository to do that: git config --add remote.freebsd.fetch '+refs/*:refs/freebsd/*' .... -which will put everything in the upstream repository into your local repository's 'refs/freebsd/' namespace. +which will put everything in the upstream repository into your local repository's `refs/freebsd/` namespace. Please note, that this also grabs all the unconverted vendor branches and the number of refs associated with them is quite large. You'll need to refer to these 'refs' with their full name because they aren't in and of Git's regular namespaces. @@ -2276,9 +1876,9 @@ would look at the log for the vendor branch for zlib starting at 1.2.10. === Collaborating with others One of the keys to good software development on a project as large as FreeBSD is the ability to collaborate with others before you push your changes to the tree. -The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, in order to share changes in a user-generated branch. +The FreeBSD project's Git repositories do not, yet, allow user-created branches to be pushed to the repository, and therefore if you wish to share your changes with others you must use another mechanism, such as a hosted GitLab or GitHub, to share changes in a user-generated branch. -The following instructions show how to set up a user-generated branch, based on the FreeBSD main branch, and push it to GitHub. +The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub. Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>> @@ -2475,7 +2075,7 @@ Those who have been given commit rights to the FreeBSD repositories must follow [[commit-steps]] [.procedure] ==== -*Procedure 1. Steps for New Committers* +*Steps for New Committers* . Add an Author Entity + @@ -2487,7 +2087,7 @@ Those who have been given commit rights to the FreeBSD repositories must follow [.filename]#doc/shared/contrib-additional.adoc# - _Remove_ the entry. Entries are sorted by first name. . Add a News Item + -[.filename]#doc/website/data/en/news/news.toml# - Add an entry. Look for the other entries that announce new committers and follow the format. Use the date from the commit bit approval email from mailto:core@FreeBSD.org[core@FreeBSD.org]. +[.filename]#doc/website/data/en/news/news.toml# - Add an entry. Look for the other entries that announce new committers and follow the format. Use the date from the commit bit approval email. . Add a PGP Key + `{des}` has written a shell script ([.filename]#doc/documentation/tools/addkey.sh#) to make this easier. See the https://cgit.freebsd.org/doc/plain/documentation/static/pgpkeys/README[README] file for more information. @@ -2507,13 +2107,15 @@ It is very important to have a current PGP/GnuPG key in the repository. The key Add an entry for each additional mentor/mentee relationship in the bottom section. . Generate a Kerberos Password + -See <<kerberos-ldap>> to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database. +See <<kerberos-ldap>> to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step). . Optional: Enable Wiki Account + -https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas. Those who do not yet have an account can follow instructions on the https://wiki.freebsd.org/AboutWiki[AboutWiki Page] to obtain one. Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account. +link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas. +Those who do not yet have an account can follow instructions on the link:https://wiki.freebsd.org/Wiki/About[Wiki/About page] to obtain one. +Contact mailto:wiki-admin@FreeBSD.org[wiki-admin@FreeBSD.org] if you need help with your Wiki account. . Optional: Update Wiki Information + -Wiki Information - After gaining access to the wiki, some people add entries to the https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks], and https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD] pages. +Wiki Information - After gaining access to the wiki, some people add entries to the https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks], https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD], and or https://wiki.freebsd.org/Community/Cats[Cats of FreeBSD] pages. . Optional: Update Ports with Personal Information + [.filename]#ports/astro/xearth/files/freebsd.committers.markers# and [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd# - Some people add entries for themselves to these files to show where they are located or the date of their birthday. @@ -2646,6 +2248,50 @@ freebsd yourusername:yourpassword .... ==== +[[smtp-setup-local-exim]] +.Using Exim +[example] +==== + +To direct a local Exim instance to forward all mail from `_example_@FreeBSD.org` + to FreeBSD.org servers, add this to Exim [.filename]#configuration#: + +[.programlisting] +.... +Routers section: (at the top of the list): +freebsd_send: + driver = manualroute + domains = !+local_domains + transport = freebsd_smtp + route_data = ${lookup {${lc:$sender_address}} lsearch {/usr/local/etc/exim/freebsd_send}} + +Transport Section: +freebsd_smtp: + driver = smtp + tls_certificate=<local certificate> + tls_privatekey=<local certificate private key> + tls_require_ciphers = EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+AESGCM:EECDH:EDH+AESGCM:EDH+aRSA:HIGH:!MEDIUM:!LOW:!aNULL:!eNULL:!LOW:!RC4:!MD5:!EXP:!PSK:!SRP:!DSS + dkim_domain = <local DKIM domain> + dkim_selector = <local DKIM selector> + dkim_private_key= <local DKIM private key> + dnssec_request_domains = * + hosts_require_auth = smtp.freebsd.org + +Authenticators: +fixed_plain: + driver = plaintext + public_name = PLAIN + client_send = ^example/mail^examplePassword +.... + +Create [.filename]#/usr/local/etc/exim/freebsd_send# with the following content: + +[.programlisting] +.... +example@freebsd.org:smtp.freebsd.org::587 +.... + +==== [[mentors]] === Mentors @@ -2665,7 +2311,7 @@ Detailed information on how to access these branches can be found in <<admin-bra == Pre-Commit Review Code review is one way to increase the quality of software. -The following guidelines apply to commits to the `head` (-CURRENT) branch of the `src` repository. +The following guidelines apply to commits to the `main` (-CURRENT) branch of the `src` repository. Other branches and the `ports` and `docs` trees have their own review policies, but these guidelines generally apply to commits requiring review: * All non-trivial changes should be reviewed before they are committed to the repository. @@ -2835,7 +2481,8 @@ The key words or phrases are: Typically used when there is no PR, for example if the issue was reported on a mailing list. -|`Submitted by:` +|`Submitted by:` + +(deprecated) |This has been deprecated with git; submitted patches should have the author set by using `git commit --author` with a full name and valid email. |`Reviewed by:` @@ -2895,9 +2542,6 @@ Approved by: re (username) |`MFC to:` |If the commit should be merged to a subset of stable branches, specify the branch names. -|`MFC with:` -|If the commit should be merged together with a previous one in a single MFC commit (for example, where this commit corrects a bug in the previous change), specify the corresponding Git hash. - |`MFH:` |If the commit is to be merged into a ports quarterly branch name, specify the quarterly branch. For example `2021Q2`. @@ -3043,7 +2687,7 @@ The FreeBSD Project suggests and uses this text as the preferred license scheme: [.programlisting] .... /*- - * SPDX-License-Identifier: BSD-2-Clause-FreeBSD + * SPDX-License-Identifier: BSD-2-Clause * * Copyright (c) [year] [your name] * @@ -3078,7 +2722,7 @@ If you have code in the tree with the advertising clause, please consider removi In fact, please consider using the above license for your code. The FreeBSD project discourages completely new licenses and variations on the standard licenses. -New licenses require the approval of the {core-email} to reside in the main repository. +New licenses require the approval of {core-email} to reside in the `src` repository. The more different licenses that are used in the tree, the more problems that this causes to those wishing to utilize this code, typically from unintended consequences from a poorly worded license. Project policy dictates that code under some non-BSD licenses must be placed only in specific sections of the repository, and in some cases, compilation must be conditional or even disabled by default. @@ -3131,13 +2775,19 @@ As of March 2021, approximately 25,000 out of 90,000 files in the tree have been == Developer Relations When working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. -Working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. -When modifying parts of the system which are maintained, formally, or informally, consider asking for review just as a developer would have before becoming a committer. +When working on a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. +When modifying parts of the system which are maintained, formally or informally, consider asking for a review just as a developer would have before becoming a committer. For ports, contact the listed `MAINTAINER` in the [.filename]#Makefile#. To determine if an area of the tree is maintained, check the MAINTAINERS file at the root of the tree. If nobody is listed, scan the revision history to see who has committed changes in the past. -An example script that lists each person who has committed to a given file along with the number of commits each person has made can be found at on `freefall` at [.filename]#~eadler/bin/whodid#. +To list the names and email addresses of all commit authors for a given file in the last 2 years and the number of commits each has authored, ordered by descending number of commits, use: + +[source,shell] +---- +% git -C /path/to/repo shortlog -sne --since="2 years" -- relative/path/to/file +---- + If queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it. [IMPORTANT] @@ -3152,7 +2802,7 @@ If a commit does results in controversy erupting, it may be advisable to conside Remember, with a version control system we can always change it back. Do not impugn the intentions of others. -If they see a different solution to a problem, or even a different problem, it is probably not because they are stupid, because they have questionable parentage, or because they are trying to destroy hard work, personal image, or FreeBSD, but basically because they have a different outlook on the world. +If they see a different solution to a problem, or even a different problem, it is probably not because they are stupid, because they have questionable parentage, or because they are trying to destroy hard work, personal image, or FreeBSD, but basically because they have a different outlook on the world. Different is good. Disagree honestly. @@ -3250,7 +2900,7 @@ If there is something you want merged from FreeBSD-CURRENT to FreeBSD-STABLE (wh `{so-name}` is the link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] and oversees the `{security-officer}`. {committers-name}:: -{svn-src-all}, {svn-ports-all} and {svn-doc-all} are the mailing lists that the version control system uses to send commit messages to. +{dev-src-all}, {dev-ports-all} and {dev-doc-all} are the mailing lists that the version control system uses to send commit messages to. _Never_ send email directly to these lists. Only send replies to this list when they are short and are directly related to a commit. @@ -3428,11 +3078,11 @@ If you have not done it before, chances are good that you do not actually know t There is no shame in asking "how in the heck do I do this?" We already know you are an intelligent person; otherwise, you would not be a committer. . Test your changes before committing them. + -This may sound obvious, but if it really were so obvious then we probably would not see so many cases of people clearly not doing this. If your changes are to the kernel, make sure you can still compile both GENERIC and LINT. If your changes are anywhere else, make sure you can still make world. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. +Please ensure your change works for <<compilers,supported toolchains>>. Please refer to the https://www.FreeBSD.org/internal/[FreeBSD Internal Page] for a list of available resources. As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available. . Do not commit to contributed software without _explicit_ approval from the respective maintainers. @@ -3460,14 +3110,70 @@ In an effort to make it easier to keep FreeBSD portable across the platforms we Our 32-bit reference platform is i386, and our 64-bit reference platform is amd64. Major design work (including major API and ABI changes) must prove itself on at least one 32-bit and at least one 64-bit platform, preferably the primary reference platforms, before it may be committed to the source tree. -The i386 and amd64 platforms were chosen due to being more readily available to developers and as representatives of more diverse processor and system designs - big versus little endian, register file versus register stack, different DMA and cache implementations, hardware page tables versus software TLB management etc. - -We will continue to re-evaluate this policy as cost and availability of the 64-bit platforms change. - Developers should also be aware of our Tier Policy for the long term support of hardware architectures. The rules here are intended to provide guidance during the development process, and are distinct from the requirements for features and architectures listed in that section. The Tier rules for feature support on architectures at release-time are more strict than the rules for changes during the development process. +[[compilers]] +=== Policy on Multiple Compilers + +FreeBSD builds with both Clang and GCC. +The project does this in a careful and controlled way to maximize benefits from this extra work, while keeping the extra work to a minimum. +Supporting both Clang and GCC improves the flexibility our users have. +These compilers have different strengths and weaknesses, and supporting both allows users to pick the best one for their needs. +Clang and GCC support similar dialects of C and C++, necessitating a relatively small amount of conditional code. +The project gains increased code coverage and improves the code quality by using features from both compilers. +The project is able to build in more user environments and leverage more CI environments by supporting this range, increasing convenience for users and giving them more tools to test with. +By carefully constraining the range of versions supported to modern versions of these compilers, the project avoids unduely increasing the testing matrix. +Older and obscure compilers, as well as older dialects of the langauges, have extremely limited support that allow user programs to build with them, but without constraining the base system to being built with them. +The exact balance continues to evolve to ensure the benefits of extra work remain greater than the burdens it imposes. +The project used to support really old Intel compilers or old GCC versions, but we traded supporting those obsolete compilers for a carefully selected range of modern compilers. +This section documents where we use different compilers, and the expectations around that. + +The FreeBSD project provides an in-tree Clang compiler. +Due to being in the tree, this compiler is the most supported compiler. +All changes must compile with it, prior to commit. +Complete testing, as appropriate for the change, should be done with this compiler. + +At any moment in time, the FreeBSD project also supports one or more out-of-tree compilers. +At present, this is GCC 12.x. +Ideally, committers should test compile with this compiler, especially for large or risky changes. +This compiler is available as the `${TARGET_ARCH}-gcc${VERSION}` package, such as package:devel/freebsd-gcc12@aarch64[aarch64-gcc12] or package:devel/freebsd-gcc12@riscv64[riscv64-gcc12]. +The project runs automated CI jobs to build everything with these compilers. +Committers are expected to fix the jobs they break with their changes. +Committers may test build with, for example `CROSS_TOOLCHAIN=aarch64-gcc12` or `CROSS_TOOLCHAIN=llvm15` where necessary. + +The FreeBSD project also has some CI pipelines on github. +For pull requests on github and some branches pushed to the github forks, a number of cross compilation jobs run. +These test FreeBSD building using a version of Clang that sometimes lags the in-tree compiler by a major version for a time. + +The FreeBSD project is also upgrading compilers. +Both Clang and GCC are fast moving targets. +Some work to change things in the tree, for example removing the old-style K&R function declarations and definitions, will land in the tree prior to the compiler landing. +Committers should try to be mindful about this and be receptive to looking into problems with their code or changes with these new compilers. +Also, just after a new compiler version hits the tree, people may need to compile things with the old version if there was an undetected regression suspected. + +In addition to the compiler, LLVM's LLD and GNU's binutils are used indirectly by the compiler. +Committers should be mindful of variations in assembler syntax and features of the linkers and ensure both variants work. +These components will be tested as part of FreeBSD's CI jobs for Clang or GCC. + +The FreeBSD project provides headers and libraries that allow other compilers to be used to build software not in the base system. +These headers have support for making the environment as strict as the standard, supporting prior dialects of ANSI-C back to C89, and other edge cases our large ports collection has uncovered. +This support constrains retirement of older standards in places like header files, but does not constrain updating the base system to newer dialects. +Nor does it require the base system to compile with these older standards as a whole. +Breaking this support will cause packages in the ports collection to fail, so should be avoided where possible, and promptly fixed when it is easy to do so. + +The FreeBSD build system currently accommodates these different environments. +As new warnings are added to compilers, the project tries to fix them. +However, sometimes these warnings require extensive rework, so are suppressed in some way by using make variables that evaluate to the proper thing depending on the compiler version. +Developers should be mindful of this, and ensure any compiler specific flags are properly conditionalized. + +==== Current Compiler Versions +The in-tree compiler is currently Clang 15.x. +Currently, GCC 12 and Clang 12, 13, 14 and 15 are tested in the github and project's CI jenkins jobs. +Work is underway to get the tree ready for Clang 16. +The oldest project supported branch has Clang 12, so the bootstrap portions of the build must work for Clang major versions 12 to 15. + === Other Suggestions When committing documentation changes, use a spell checker before committing. @@ -3809,8 +3515,8 @@ Merging commits to the quarterly branch (a process we call MFH for a historical % git push .... -where '$HASH' is the hash of the commit you want to copy over to the quarterly branch. -The -x parameter ensures the hash '$HASH' of the main branch is included in the new commit message of the quarterly branch. +where `$HASH` is the hash of the commit you want to copy over to the quarterly branch. +The `-x` parameter ensures the hash `$HASH` of the `main` branch is included in the new commit message of the quarterly branch. [[ports-qa-new-category]] === Creating a New Category @@ -3845,7 +3551,7 @@ To do this, you will need to: . If you want to be really thorough, now might be a good time to run man:portlint[1]. ====== + -. Check that the ``PKGORIGIN``s are correct. The ports system uses each port's `CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like man:pkg_version[1] and man:portupgrade[1] fail. +. Check that the ``PKGORIGIN``s are correct. The ports system uses each port's `CATEGORIES` entry to create its `PKGORIGIN`, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like man:pkg-version[8] and man:portupgrade[1] fail. + To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh`. This will check every port in the ports tree, even those not connected to the build, so you can run it directly after the move operation. Hint: do not forget to look at the ``PKGORIGIN``s of any slave ports of the ports you just moved! . On your own local system, test the proposed changes: first, comment out the SUBDIR entries in the old ports' categories' [.filename]##Makefile##s; then enable building the new category in [.filename]#ports/Makefile#. Run make checksubdirs in the affected category directories to check the SUBDIR entries. Next, in the [.filename]#ports/# directory, run make index. This can take over 40 minutes on even modern systems; however, it is a necessary step to prevent problems for other people. @@ -3933,7 +3639,7 @@ Full package builds will be done with the patches provided by the submitter, and == Issues Specific to Developers Who Are Not Committers A few people who have access to the FreeBSD machines do not have commit bits. -Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them). +Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them). In particular, we recommend that you read: * <<admin>> @@ -3950,11 +3656,11 @@ Get your mentor to add you to the "Additional Contributors" ([.filename]#doc/sha [[google-analytics]] == Information About Google Analytics -As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project website to collect anonymized usage statistics regarding usage of the site. +As of December 12, 2012, Google Analytics was enabled on the FreeBSD Project website to collect anonymized usage statistics regarding usage of the site. [NOTE] ==== -As of March 3, 2022, Googla Analytics was removed from the FreeBSD Project. +As of March 3, 2022, Google Analytics was removed from the FreeBSD Project. ==== [[misc]] @@ -3993,7 +3699,7 @@ FreeBSD committers can get a free 4-CD or DVD set at conferences from http://www https://gandi.net[Gandi] provides website hosting, cloud computing, domain registration, and X.509 certificate services. Gandi offers an E-rate discount to all FreeBSD developers. -In order to streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. +To streamline the process of getting the discount first set up a Gandi account, fill in the billing information and select the currency. Then send an mail to mailto:non-profit@gandi.net[non-profit@gandi.net] using your `@freebsd.org` mail address, and indicate your Gandi handle. [[benefits-rsync]] @@ -4002,3 +3708,15 @@ Then send an mail to mailto:non-profit@gandi.net[non-profit@gandi.net] using you https://rsync.net[rsync.net] provides cloud storage for offsite backup that is optimized for UNIX users. Their service runs entirely on FreeBSD and ZFS. rsync.net offers a free-forever 500 GB account to FreeBSD developers. Simply sign up at https://www.rsync.net/freebsd.html[https://www.rsync.net/freebsd.html] using your `@freebsd.org` address to receive this free account. + +[[benefits-jetbrains]] +=== `JetBrains` + +https://www.jetbrains.com[JetBrains] is a software development company which makes tools for software developers and project managers. The company offers many integrated development environments (IDEs) for different programming languages. + +JetBrains offers 100 free yearly licenses for all https://www.jetbrains.com/products[JetBrains IDE products]. Simply sign up at https://account.jetbrains.com/a/322tl3z7[https://account.jetbrains.com/a/322tl3z7] using your `@freebsd.org` address and the account will have a license attached to it automatically. Once the account is active, use it in any of the products to activate them and you're done. + +[IMPORTANT] +==== +Please, only use these licences personally and do not share them with anyone outside of the FreeBSD project, as that would be a violation of the terms of the donation. +==== diff --git a/documentation/content/en/articles/committers-guide/_index.po b/documentation/content/en/articles/committers-guide/_index.po new file mode 100644 index 0000000000..e1d331ec20 --- /dev/null +++ b/documentation/content/en/articles/committers-guide/_index.po @@ -0,0 +1,8413 @@ +# 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: 2023-05-21 14:43-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: YAML Front Matter: description +#: documentation/content/en/articles/committers-guide/_index.adoc:1 +#, no-wrap +msgid "Introductory information for FreeBSD committers" +msgstr "" + +#. type: Title = +#: documentation/content/en/articles/committers-guide/_index.adoc:1 +#: documentation/content/en/articles/committers-guide/_index.adoc:12 +#, no-wrap +msgid "Committer's Guide" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:45 +msgid "Abstract" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:48 +msgid "" +"This document provides information for the FreeBSD committer community. All " +"new committers should read this document before they start, and existing " +"committers are strongly encouraged to review it from time to time." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:53 +msgid "" +"Almost all FreeBSD developers have commit rights to one or more " +"repositories. However, a few developers do not, and some of the information " +"here applies to them as well. (For instance, some people only have rights " +"to work with the Problem Report database.) Please see <<non-committers>> " +"for more information." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:55 +msgid "" +"This document may also be of interest to members of the FreeBSD community " +"who want to learn more about how the project works." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:57 +msgid "'''" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:61 +#, no-wrap +msgid "Administrative Details" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:68 +#, no-wrap +msgid "_Login Methods_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:70 +#, no-wrap +msgid "man:ssh[1], protocol 2 only" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:71 +#, no-wrap +msgid "_Main Shell Host_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:73 +#, no-wrap +msgid "`freefall.FreeBSD.org`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:74 +#, no-wrap +msgid "_Reference Machines_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:76 +#, no-wrap +msgid "`ref*.FreeBSD.org`, `universe*.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:77 +#, no-wrap +msgid "_SMTP Host_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:79 +#, no-wrap +msgid "`smtp.FreeBSD.org:587` (see also <<smtp-setup>>)." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:80 +#, no-wrap +msgid "`_src/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:82 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/src.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:83 +#, no-wrap +msgid "`_doc/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:85 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/doc.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:86 +#, no-wrap +msgid "`_ports/_` Git Repository" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:88 +#, no-wrap +msgid "`ssh://git@gitrepo.FreeBSD.org/ports.git`" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:89 +#, no-wrap +msgid "_Internal Mailing Lists_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:91 +#, no-wrap +msgid "developers (technically called all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists can be found in the files [.filename]#/local/mail/repository-name-developers-archive# and [.filename]#/local/mail/repository-name-committers-archive# on `freefall.FreeBSD.org`.)" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:92 +#, no-wrap +msgid "_Core Team monthly reports_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:94 +#, no-wrap +msgid "[.filename]#/home/core/public/reports# on the `FreeBSD.org` cluster." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:95 +#, no-wrap +msgid "_Ports Management Team monthly reports_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:97 +#, no-wrap +msgid "[.filename]#/home/portmgr/public/monthly-reports# on the `FreeBSD.org` cluster." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:98 +#, no-wrap +msgid "_Noteworthy `src/` Git Branches:_" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:99 +#, no-wrap +msgid "`stable/n` (`n`-STABLE), `main` (-CURRENT)" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:102 +msgid "" +"man:ssh[1] is required to connect to the project hosts. For more " +"information, see <<ssh.guide>>." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:104 +msgid "Useful links:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:106 +msgid "link:https://www.FreeBSD.org/internal/[FreeBSD Project Internal Pages]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:107 +msgid "link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:108 +msgid "" +"link:https://www.FreeBSD.org/administration/[FreeBSD Project Administrative " +"Groups]" +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:110 +#, no-wrap +msgid "OpenPGP Keys for FreeBSD" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:115 +msgid "" +"Cryptographic keys conforming to the OpenPGP (__Pretty Good Privacy__) " +"standard are used by the FreeBSD project to authenticate committers. " +"Messages carrying important information like public SSH keys can be signed " +"with the OpenPGP key to prove that they are really from the committer. See " +"https://nostarch.com/releases/pgp_release.pdf[PGP & GPG: Email for the " +"Practical Paranoid by Michael Lucas] and http://en.wikipedia.org/wiki/" +"Pretty_Good_Privacy[] for more information." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:117 +#, no-wrap +msgid "Creating a Key" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:121 +msgid "" +"Existing keys can be used, but should be checked with [." +"filename]#documentation/tools/checkkey.sh# first. In this case, make sure " +"the key has a FreeBSD user ID." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:123 +msgid "" +"For those who do not yet have an OpenPGP key, or need a new key to meet " +"FreeBSD security requirements, here we show how to generate one." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:128 +msgid "" +"Install [.filename]#security/gnupg#. Enter these lines in [.filename]#~/." +"gnupg/gpg.conf# to set minimum acceptable defaults:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:139 +#, no-wrap +msgid "" +"fixed-list-mode\n" +"keyid-format 0xlong\n" +"personal-digest-preferences SHA512 SHA384 SHA256 SHA224\n" +"default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed\n" +"verify-options show-uid-validity\n" +"list-options show-uid-validity\n" +"sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g\n" +"cert-digest-algo SHA512\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:141 +msgid "Generate a key:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:148 +#, no-wrap +msgid "" +"% gpg --full-gen-key\n" +"gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc.\n" +"This is free software: you are free to change and redistribute it.\n" +"There is NO WARRANTY, to the extent permitted by law.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:169 +#, no-wrap +msgid "" +"Warning: using insecure memory!\n" +"Please select what kind of key you want:\n" +" (1) RSA and RSA (default)\n" +" (2) DSA and Elgamal\n" +" (3) DSA (sign only)\n" +" (4) RSA (sign only)\n" +"Your selection? 1\n" +"RSA keys may be between 1024 and 4096 bits long.\n" +"What keysize do you want? (2048) 2048 <.>\n" +"Requested keysize is 2048 bits\n" +"Please specify how long the key should be valid.\n" +"\t 0 = key does not expire\n" +" <n> = key expires in n days\n" +" <n>w = key expires in n weeks\n" +" <n>m = key expires in n months\n" +" <n>y = key expires in n years\n" +"Key is valid for? (0) 3y <.>\n" +"Key expires at Wed Nov 4 17:20:20 2015 MST\n" +"Is this correct? (y/N) y\n" +"GnuPG needs to construct a user ID to identify your key.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:175 +#, no-wrap +msgid "" +"Real name: Chucky Daemon <.>\n" +"Email address: notreal@example.com\n" +"Comment:\n" +"You selected this USER-ID:\n" +"\"Chucky Daemon <notreal@example.com>\"\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:178 +#, no-wrap +msgid "" +"Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o\n" +"You need a Passphrase to protect your secret key.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:181 +msgid "" +"2048-bit keys with a three-year expiration provide adequate protection at " +"present (2022-10)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:183 +msgid "" +"A three year key lifespan is short enough to obsolete keys weakened by " +"advancing computer power, but long enough to reduce key management problems." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:185 +msgid "" +"Use your real name here, preferably matching that shown on government-issued " +"ID to make it easier for others to verify your identity. Text that may help " +"others identify you can be entered in the `Comment` section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:189 +msgid "" +"After the email address is entered, a passphrase is requested. Methods of " +"creating a secure passphrase are contentious. Rather than suggest a single " +"way, here are some links to sites that describe various methods: https://" +"world.std.com/~reinhold/diceware.html[], https://www.iusmentis.com/security/" +"passphrasefaq/[], https://xkcd.com/936/[], https://en.wikipedia.org/wiki/" +"Passphrase[]." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:193 +msgid "" +"Protect the private key and passphrase. If either the private key or " +"passphrase may have been compromised or disclosed, immediately notify mailto:" +"accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:195 +msgid "" +"Committing the new key is shown in <<commit-steps, Steps for New " +"Committers>>." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:197 +#, no-wrap +msgid "Kerberos and LDAP web Password for FreeBSD Cluster" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:202 +msgid "" +"The FreeBSD cluster requires a Kerberos password to access certain " +"services. The Kerberos password also serves as the LDAP web password, since " +"LDAP is proxying to Kerberos in the cluster. Some of the services which " +"require this include:" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:204 +msgid "https://bugs.freebsd.org/bugzilla[Bugzilla]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:205 +msgid "https://ci.freebsd.org[Jenkins]" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:207 +msgid "" +"To create a new Kerberos account in the FreeBSD cluster, or to reset a " +"Kerberos password for an existing account using a random password generator:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:211 +#, no-wrap +msgid "% ssh kpasswd.freebsd.org\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:216 +msgid "This must be done from a machine outside of the FreeBSD.org cluster." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:219 +msgid "" +"A Kerberos password can also be set manually by logging into `freefall." +"FreeBSD.org` and running:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:223 +#, no-wrap +msgid "% kpasswd\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:229 +msgid "" +"Unless the Kerberos-authenticated services of the FreeBSD.org cluster have " +"been used previously, `Client unknown` will be shown. This error means that " +"the `ssh kpasswd.freebsd.org` method shown above must be used first to " +"initialize the Kerberos account." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:232 +#, no-wrap +msgid "Commit Bit Types" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:238 +msgid "" +"The FreeBSD repository has a number of components which, when combined, " +"support the basic operating system source, documentation, third party " +"application ports infrastructure, and various maintained utilities. When " +"FreeBSD commit bits are allocated, the areas of the tree where the bit may " +"be used are specified. Generally, the areas associated with a bit reflect " +"who authorized the allocation of the commit bit. Additional areas of " +"authority may be added at a later date: when this occurs, the committer " +"should follow normal commit bit allocation procedures for that area of the " +"tree, seeking approval from the appropriate entity and possibly getting a " +"mentor for that area for some period of time." +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:244 +#, no-wrap +msgid "__Committer Type__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:245 +#, no-wrap +msgid "__Responsible__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:247 +#, no-wrap +msgid "__Tree Components__" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:248 +#, no-wrap +msgid "src" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:249 +#, no-wrap +msgid "core@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:251 +#, no-wrap +msgid "src/" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:252 +#, no-wrap +msgid "doc" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:253 +#, no-wrap +msgid "doceng@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:255 +#, no-wrap +msgid "doc/, ports/, src/ documentation" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:256 +#, no-wrap +msgid "ports" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:257 +#, no-wrap +msgid "portmgr@" +msgstr "" + +#. type: Table +#: documentation/content/en/articles/committers-guide/_index.adoc:258 +#, no-wrap +msgid "ports/" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:263 +msgid "" +"Commit bits allocated prior to the development of the notion of areas of " +"authority may be appropriate for use in many parts of the tree. However, " +"common sense dictates that a committer who has not previously worked in an " +"area of the tree seek review prior to committing, seek approval from the " +"appropriate responsible party, and/or work with a mentor. Since the rules " +"regarding code maintenance differ by area of the tree, this is as much for " +"the benefit of the committer working in an area of less familiarity as it is " +"for others working on the tree." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:265 +msgid "" +"Committers are encouraged to seek review for their work as part of the " +"normal development process, regardless of the area of the tree where the " +"work is occurring." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:266 +#, no-wrap +msgid "Policy for Committer Activity in Other Trees" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:269 +msgid "" +"All committers may modify [.filename]#src/share/misc/committers-*.dot#, [." +"filename]#src/usr.bin/calendar/calendars/calendar.freebsd#, and [." +"filename]#ports/astro/xearth/files#." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:270 +msgid "" +"doc committers may commit documentation changes to [.filename]#src# files, " +"such as manual pages, READMEs, fortune databases, calendar files, and " +"comment fixes without approval from a src committer, subject to the normal " +"care and tending of commits." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:272 +msgid "" +"Any committer may make changes to any other tree with an \"Approved by\" " +"from a non-mentored committer with the appropriate bit. Mentored committers " +"can provide a \"Reviewed by\" but not an \"Approved by\"." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:273 +msgid "" +"Committers can acquire an additional bit by the usual process of finding a " +"mentor who will propose them to core, doceng, or portmgr, as appropriate. " +"When approved, they will be added to 'access' and the normal mentoring " +"period will ensue, which will involve a continuing of \"Approved by\" for " +"some period." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:275 +#, no-wrap +msgid "Documentation Implicit (Blanket) Approval" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:279 +msgid "" +"Some types of fixes have \"blanket approval\" from the {doceng}, allowing " +"any committer to fix those categories of problems on any part of the doc " +"tree. These fixes do not need approval or review from a doc committer if " +"the author doesn't have a doc commit bit." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:281 +msgid "Blanket approval applies to these types of fixes:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:283 +msgid "Typos" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:284 +msgid "Trivial fixes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:286 +msgid "" +"Punctuation, URLs, dates, paths and file names with outdated or incorrect " +"information, and other common mistakes that may confound the readers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:289 +msgid "" +"Over the years, some implicit approvals were granted in the doc tree. This " +"list shows the most common cases:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:291 +msgid "" +"Changes in [.filename]#documentation/content/en/books/porters-handbook/" +"versions/_index.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:293 +msgid "" +"extref:{porters-handbook}versions/[__FreeBSD_version Values (Porter's " +"Handbook)], mainly used for src committers." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:294 +msgid "Changes in [.filename]#doc/shared/contrib-additional.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:296 +msgid "" +"extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] " +"maintenance." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:297 +msgid "All link:#commit-steps[Steps for New Committers], doc related" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:298 +msgid "Security advisories; Errata Notices; Releases;" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:300 +msgid "Used by {security-officer} and {re}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:301 +msgid "Changes in [.filename]#website/content/en/donations/donors.adoc#" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:303 +msgid "Used by {donations}." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:305 +msgid "" +"Before any commit, a build test is necessary; see the 'Overview' and 'The " +"FreeBSD Documentation Build Process' sections of the extref:{fdp-primer}" +"[FreeBSD Documentation Project Primer for New Contributors] for more details." +msgstr "" + +#. type: Title == +#: documentation/content/en/articles/committers-guide/_index.adoc:307 +#, no-wrap +msgid "Git Primer" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:310 +#, no-wrap +msgid "Git basics" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:317 +msgid "" +"When one searches for \"Git Primer\" a number of good ones come up. Daniel " +"Miessler's link:https://danielmiessler.com/study/git/[A git primer] and " +"Willie Willus' link:https://gist.github.com/" +"williewillus/068e9a8543de3a7ef80adb2938657b6b[Git - Quick Primer] are both " +"good overviews. The Git book is also complete, but much longer https://git-" +"scm.com/book/en/v2. There is also this website https://dangitgit.com/ for " +"common traps and pitfalls of Git, in case you need guidance to fix things " +"up. Finally, an introduction link:https://eagain.net/articles/git-for-" +"computer-scientists/[targeted at computer scientists] has proven helpful to " +"some at explaining the Git world view." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:319 +msgid "" +"This document will assume that you've read through it and will try not to " +"belabor the basics (though it will cover them briefly)." +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:321 +#, no-wrap +msgid "Git Mini Primer" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:324 +msgid "" +"This primer is less ambitiously scoped than the old Subversion Primer, but " +"should cover the basics." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:325 +#, no-wrap +msgid "Scope" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:331 +msgid "" +"If you want to download FreeBSD, compile it from sources, and generally keep " +"up to date that way, this primer is for you. It covers getting the sources, " +"updating the sources, bisecting and touches briefly on how to cope with a " +"few local changes. It covers the basics, and tries to give good pointers to " +"more in-depth treatment for when the reader finds the basics insufficient. " +"Other sections of this guide cover more advanced topics related to " +"contributing to the project." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:335 +msgid "" +"The goal of this section is to highlight those bits of Git needed to track " +"sources. They assume a basic understanding of Git. There are many primers " +"for Git on the web, but the https://git-scm.com/book/en/v2[Git Book] " +"provides one of the better treatments." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:337 +#, no-wrap +msgid "Getting Started For Developers" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:340 +msgid "" +"This section describes the read-write access for committers to push the " +"commits from developers or contributors." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:342 +#, no-wrap +msgid "Daily use" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:345 +msgid "Clone the repository:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:349 +#, no-wrap +msgid "% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/${repo}.git\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:352 +msgid "Then you should have the official mirrors as your remote:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:358 +#, no-wrap +msgid "" +"% git remote -v\n" +"freebsd https://git.freebsd.org/${repo}.git (fetch)\n" +"freebsd https://git.freebsd.org/${repo}.git (push)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:361 +msgid "Configure the FreeBSD committer data:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:364 +msgid "" +"The commit hook in repo.freebsd.org checks the \"Commit\" field matches the " +"committer's information in FreeBSD.org. The easiest way to get the " +"suggested config is by executing `/usr/local/bin/gen-gitconfig.sh` script on " +"freefall:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:371 +#, no-wrap +msgid "" +"% gen-gitconfig.sh\n" +"[...]\n" +"% git config user.name (your name in gecos)\n" +"% git config user.email (your login)@FreeBSD.org\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:374 +msgid "Set the push URL:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:378 +#, no-wrap +msgid "% git remote set-url --push freebsd git@gitrepo.freebsd.org:${repo}.git\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:381 +msgid "" +"Then you should have separated fetch and push URLs as the most efficient " +"setup:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:387 +#, no-wrap +msgid "" +"% git remote -v\n" +"freebsd https://git.freebsd.org/${repo}.git (fetch)\n" +"freebsd git@gitrepo.freebsd.org:${repo}.git (push)\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:390 +msgid "" +"Again, note that `gitrepo.freebsd.org` has been canonicalized to `repo." +"freebsd.org`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:392 +msgid "Install commit message template hook:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:397 +#, no-wrap +msgid "" +"% fetch https://cgit.freebsd.org/src/plain/tools/tools/git/hooks/prepare-commit-msg -o .git/hooks\n" +"% chmod 755 .git/hooks/prepare-commit-msg\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:400 +#, no-wrap +msgid "\"admin\" branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:403 +msgid "" +"The `access` and `mentors` files are stored in an orphan branch, `internal/" +"admin`, in each repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:405 +msgid "" +"Following example is how to check out the `internal/admin` branch to a local " +"branch named `admin`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:411 +#, no-wrap +msgid "" +"% git config --add remote.freebsd.fetch '+refs/internal/*:refs/internal/*'\n" +"% git fetch\n" +"% git checkout -b admin internal/admin\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:413 +msgid "Alternatively, you can add a worktree for the `admin` branch:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:417 +#, no-wrap +msgid "git worktree add -b admin ../${repo}-admin internal/admin\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:421 +msgid "" +"For browsing `internal/admin` branch on web: `https://cgit.freebsd.org/" +"${repo}/log/?h=internal/admin`" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:423 +msgid "For pushing, either specify the full refspec:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:427 +#, no-wrap +msgid "git push freebsd HEAD:refs/internal/admin\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:429 +#, no-wrap +msgid "Keeping Current With The FreeBSD src Tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:436 +msgid "" +"First step: cloning a tree. This downloads the entire tree. There are two " +"ways to download. Most people will want to do a deep clone of the " +"repository. However, there are times when you may wish to do a shallow " +"clone." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:437 +#, no-wrap +msgid "Branch Names" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:439 +msgid "FreeBSD-CURRENT uses the `main` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:441 +msgid "`main` is the default branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:443 +msgid "For FreeBSD-STABLE, branch names include `stable/12` and `stable/13`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:445 +msgid "" +"For FreeBSD-RELEASE, release engineering branch names include `releng/12.4` " +"and `releng/13.2`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:447 +msgid "https://www.freebsd.org/releng/[] shows:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:449 +msgid "`main` and `stable/⋯` branches open" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:450 +msgid "`releng/⋯` branches, each of which is frozen when a release is tagged." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:452 +msgid "Examples:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:454 +msgid "" +"tag https://cgit.freebsd.org/src/tag/?h=release/13.1.0[release/13.1.0] on " +"the https://cgit.freebsd.org/src/log/?h=releng/13.1[releng/13.1] branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:455 +msgid "" +"tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on " +"the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:456 +#, no-wrap +msgid "Repositories" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:459 +msgid "" +"Please see the <<admin,Administrative Details>> for the latest information " +"on where to get FreeBSD sources. $URL below can be obtained from that page." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:462 +msgid "" +"Note: The project doesn't use submodules as they are a poor fit for our " +"workflows and development model. How we track changes in third-party " +"applications is discussed elsewhere and generally of little concern to the " +"casual user." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:463 +#, no-wrap +msgid "Deep Clone" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:467 +msgid "" +"A deep clone pulls in the entire tree, as well as all the history and " +"branches. It is the easiest to do. It also allows you to use Git's " +"worktree feature to have all your active branches checked out into separate " +"directories but with only one copy of the repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:470 +#, no-wrap +msgid "% git clone -o freebsd $URL -b branch [<directory>]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:475 +msgid "" +"will create a deep clone. `branch` should be one of the branches listed in " +"the previous section. If no `branch` is given: the default (`main`) will be " +"used. If no `<directory>` is given: the name of the new directory will " +"match the name of the repo ([.filename]#doc#, [.filename]#ports# or [." +"filename]#src#)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:480 +msgid "" +"You will want a deep clone if you are interested in the history, plan on " +"making local changes, or plan on working on more than one branch. It is the " +"easiest to keep up to date as well. If you are interested in the history, " +"but are working with only one branch and are short on space, you can also " +"use --single-branch to only download the one branch (though some merge " +"commits will not reference the merged-from branch which may be important for " +"some users who are interested in detailed versions of history)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:481 +#, no-wrap +msgid "Shallow Clone" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:487 +msgid "" +"A shallow clone copies just the most current code, but none or little of the " +"history. This can be useful when you need to build a specific revision of " +"FreeBSD, or when you are just starting out and plan to track the tree more " +"fully. You can also use it to limit history to only so many revisions. " +"However, see below for a significant limitation of this approach." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:491 +#, no-wrap +msgid "% git clone -o freebsd -b branch --depth 1 $URL [dir]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:496 +msgid "" +"This clones the repository, but only has the most recent version in the " +"repository. The rest of the history is not downloaded. Should you change " +"your mind later, you can do `git fetch --unshallow` to get the old history." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:501 +msgid "" +"When you make a shallow clone, you will lose the commit count in your uname " +"output. This can make it more difficult to determine if your system needs " +"to be updated when a security advisory is issued." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:503 +#, no-wrap +msgid "Building" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:507 +msgid "" +"Once you've downloaded, building is done as described in the handbook, e.g.:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:514 +#, no-wrap +msgid "" +"% cd src\n" +"% make buildworld\n" +"% make buildkernel\n" +"% make installkernel\n" +"% make installworld\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:516 +msgid "so that won't be covered in depth here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:519 +msgid "" +"If you want to build a custom kernel, extref:{handbook}[the kernel config " +"section, kernelconfig] of the FreeBSD Handbook recommends creating a file " +"MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. To have " +"MYKERNEL disregarded by Git, it can be added to .git/info/exclude." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:520 +#, no-wrap +msgid "Updating" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:524 +msgid "" +"To update both types of trees uses the same commands. This pulls in all the " +"revisions since your last update." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:527 +#, no-wrap +msgid "% git pull --ff-only\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:532 +msgid "" +"will update the tree. In Git, a 'fast forward' merge is one that only needs " +"to set a new branch pointer and doesn't need to re-create the commits. By " +"always doing a fast forward merge/pull, you'll ensure that you have an exact " +"copy of the FreeBSD tree. This will be important if you want to maintain " +"local patches." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:535 +msgid "" +"See below for how to manage local changes. The simplest is to use `--" +"autostash` on the `git pull` command, but more sophisticated options are " +"available." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:536 +#, no-wrap +msgid "Selecting a Specific Version" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:540 +msgid "" +"In Git, `git checkout` checks out both branches and specific versions. " +"Git's versions are the long hashes rather than a sequential number." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:542 +msgid "" +"When you checkout a specific version, just specify the hash you want on the " +"command line (the git log command can help you decide which hash you might " +"want):" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:545 +#, no-wrap +msgid "% git checkout 08b8197a74\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:548 +msgid "" +"and you have that checked out. You will be greeted with a message similar " +"to the following:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:551 +#, no-wrap +msgid "Note: checking out '08b8197a742a96964d2924391bf9fdfeb788865d'.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:555 +#, no-wrap +msgid "" +"You are in a 'detached HEAD' state. You can look around, make experimental\n" +"changes and commit them, and you can discard any commits you make in this\n" +"state without impacting any branches by performing another checkout.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:558 +#, no-wrap +msgid "" +"If you want to create a new branch to retain commits you create, you may\n" +"do so (now or later) by using -b with the checkout command again. Example:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:560 +#: documentation/content/en/articles/committers-guide/_index.adoc:1668 +#, no-wrap +msgid " git checkout -b <new-branch-name>\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:562 +#, no-wrap +msgid "HEAD is now at 08b8197a742a hook gpiokeys.4 to the build\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:566 +msgid "" +"where the last line is generated from the hash you are checking out and the " +"first line of the commit message from that revision. The hash can be " +"abbreviated to the shortest unique length. Git itself is inconsistent about " +"how many digits it displays." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:567 +#, no-wrap +msgid "Bisecting" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:571 +msgid "" +"Sometimes, things go wrong. The last version worked, but the one you just " +"updated to does not. A developer may ask you to bisect the problem to track " +"down which commit caused the regression." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:576 +msgid "" +"Git makes bisecting changes easy with a powerful `git bisect` command. " +"Here's a brief outline of how to use it. For more information, you can view " +"https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-" +"elimination or https://git-scm.com/docs/git-bisect for more details. The " +"man git-bisect page is good at describing what can go wrong, what to do when " +"versions won't build, when you want to use terms other than 'good' and " +"'bad', etc, none of which will be covered here." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:583 +msgid "" +"`git bisect start --first-parent` will start the bisection process. Next, " +"you need to tell a range to go through. `git bisect good XXXXXX` will tell " +"it the working version and `git bisect bad XXXXX` will tell it the bad " +"version. The bad version will almost always be HEAD (a special tag for what " +"you have checked out). The good version will be the last one you checked " +"out. The `--first-parent` argument is necessary so that subsequent `git " +"bisect` commands do not try to check out a vendor branch which lacks the " +"full FreeBSD source tree." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:587 +msgid "" +"If you want to know the last version you checked out, you should use `git " +"reflog`:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:592 +#, no-wrap +msgid "" +"5ef0bd68b515 (HEAD -> main, freebsd/main, freebsd/HEAD) HEAD@{0}: pull --ff-only: Fast-forward\n" +"a8163e165c5b (upstream/main) HEAD@{1}: checkout: moving from b6fb97efb682994f59b21fe4efb3fcfc0e5b9eeb to main\n" +"...\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:596 +msgid "" +"shows me moving the working tree to the `main` branch (a816...) and then " +"updating from upstream (to 5ef0...). In this case, bad would be HEAD (or " +"5rf0bd68) and good would be a8163e165. As you can see from the output, " +"HEAD@{1} also often works, but isn't foolproof if you have done other things " +"to your Git tree after updating, but before you discover the need to bisect." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:600 +msgid "" +"Set the 'good' version first, then set the bad (though the order doesn't " +"matter). When you set the bad version, it will give you some statistics on " +"the process:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:607 +#, no-wrap +msgid "" +"% git bisect start --first-parent\n" +"% git bisect good a8163e165c5b\n" +"% git bisect bad HEAD\n" +"Bisecting: 1722 revisions left to test after this (roughly 11 steps)\n" +"[c427b3158fd8225f6afc09e7e6f62326f9e4de7e] Fixup r361997 by balancing parens. Duh.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:616 +msgid "" +"You would then build/install that version. If it's good you'd type `git " +"bisect good` otherwise `git bisect bad`. If the version doesn't compile, " +"type `git bisect skip`. You will get a similar message to the above after " +"each step. When you are done, report the bad version to the developer (or " +"fix the bug yourself and send a patch). `git bisect reset` will end the " +"process and return you back to where you started (usually tip of `main`). " +"Again, the git-bisect manual (linked above) is a good resource for when " +"things go wrong or for unusual cases." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:618 +#, no-wrap +msgid "Signing the commits, tags, and pushes, with GnuPG" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:623 +msgid "" +"Git knows how to sign commits, tags, and pushes. When you sign a Git commit " +"or a tag, you can prove that the code you submitted came from you and wasn't " +"altered while you were transferring it. You also can prove that you " +"submitted the code and not someone else." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:625 +msgid "" +"A more in-depth documentation on signing commits and tags can be found in " +"the https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work[Git Tools - " +"Signing Your Work] chapter of the Git's book." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:627 +msgid "" +"The rationale behind signing pushes can be found in the https://github.com/" +"git/git/commit/a85b377d0419a9dfaca8af2320cc33b051cbed04[commit that " +"introduced the feature]." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:630 +msgid "" +"The best way is to simply tell Git you always want to sign commits, tags, " +"and pushes. You can do this by setting a few configuration variables:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:637 +#, no-wrap +msgid "" +"% git config --add user.signingKey LONG-KEY-ID\n" +"% git config --add commit.gpgSign true\n" +"% git config --add tag.gpgSign true\n" +"% git config --add push.gpgSign if-asked\n" +msgstr "" + +#. push.gpgSign should probably be set to `yes` once we enable it, or be set with --global, so that it is enabled for all repositories. +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:645 +msgid "" +"To avoid possible collisions, make sure you give a long key id to Git. You " +"can get the long id with: `gpg --list-secret-keys --keyid-format LONG`." +msgstr "" + +#. type: delimited block = 6 +#: documentation/content/en/articles/committers-guide/_index.adoc:651 +msgid "" +"To use specific subkeys, and not have GnuPG to resolve the subkey to a " +"primary key, attach `!` to the key. For example, to encrypt for the subkey " +"`DEADBEEF`, use `DEADBEEF!`." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:653 +#, no-wrap +msgid "Verifying signatures" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:656 +msgid "" +"Commit signatures can be verified by running either `git verify-commit " +"<commit hash>`, or `git log --show-signature`." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:658 +msgid "" +"Tag signatures can be verified with `git verity-tag <tag name>`, or `git tag " +"-v <tag name>`." +msgstr "" + +# +# +#. Commented out for now until we decide what to do. +#. Git pushes are a bit different, they live in a special ref in the repository. +#. TODO: write how to verify them +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:667 +#, no-wrap +msgid "Ports Considerations" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:670 +msgid "" +"The ports tree operates the same way. The branch names are different and " +"the repositories are in different locations." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:673 +msgid "" +"The cgit repository web interface for use with web browsers is at https://" +"cgit.FreeBSD.org/ports/ . The production Git repository is at https://git." +"FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or " +"anongit@git.FreeBSD.org:ports.git)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:677 +msgid "" +"There is also a mirror on GitHub, see extref:{handbook}/mirrors[External " +"mirrors, mirrors] for an overview. The _latest_ branch is `main`. The " +"_quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:679 +#, no-wrap +msgid "Commit message formats" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:683 +msgid "" +"A hook is available in the ports repository to help you write up your commit " +"messages in https://cgit.freebsd.org/ports/tree/.hooks/prepare-commit-msg[." +"hooks/prepare-commit-message]. It can be enabled by running ``git config --" +"add core.hooksPath .hooks``." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:685 +msgid "" +"The main point being that a commit message should be formatted in the " +"following way:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:688 +#, no-wrap +msgid "category/port: Summary.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:690 +#, no-wrap +msgid "Description of why the changes where made.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:692 +#, no-wrap +msgid "PR:\t 12345\n" +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:698 +msgid "" +"The first line is the subject of the commit, it contains what port was " +"changed, and a summary of the commit. It should contain 50 characters or " +"less." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:700 +msgid "A blank line should separate it from the rest of the commit message." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:702 +msgid "" +"The rest of the commit message should be wrapped at the 72 characters " +"boundary." +msgstr "" + +#. type: delimited block = 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:704 +msgid "" +"Another blank line should be added if there are any metadata fields, so that " +"they are easily distinguishable from the commit message." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:706 +#, no-wrap +msgid "Managing Local Changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:709 +msgid "" +"This section addresses tracking local changes. If you have no local " +"changes, you can stop reading now (it is the last section and OK to skip)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:715 +msgid "" +"One item that is important for all of them: all changes are local until " +"pushed. Unlike Subversion, Git uses a distributed model. For users, for " +"most things, there is very little difference. However, if you have local " +"changes, you can use the same tool to manage them as you use to pull in " +"changes from FreeBSD. All changes that you have not pushed are local and " +"can easily be modified (git rebase, discussed below does this)." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:716 +#, no-wrap +msgid "Keeping local changes" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:723 +msgid "" +"The simplest way to keep local changes (especially trivial ones) is to use " +"`git stash`. In its simplest form, you use `git stash` to record the " +"changes (which pushes them onto the stash stack). Most people use this to " +"save changes before updating the tree as described above. They then use " +"`git stash apply` to re-apply them to the tree. The stash is a stack of " +"changes that can be examined with `git stash list`. The git-stash man page " +"(https://git-scm.com/docs/git-stash) has all the details." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:727 +msgid "" +"This method is suitable when you have tiny tweaks to the tree. When you " +"have anything non trivial, you'll likely be better off keeping a local " +"branch and rebasing. Stashing is also integrated with the `git pull` " +"command: just add `--autostash` to the command line." +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:728 +#, no-wrap +msgid "Keeping a local branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:735 +msgid "" +"It is much easier to keep a local branch with Git than Subversion. In " +"Subversion you need to merge the commit, and resolve the conflicts. This is " +"manageable, but can lead to a convoluted history that's hard to upstream " +"should that ever be necessary, or hard to replicate if you need to do so. " +"Git also allows one to merge, along with the same problems. That's one way " +"to manage the branch, but it's the least flexible." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:739 +msgid "" +"In addition to merging, Git supports the concept of 'rebasing' which avoids " +"these issues. The `git rebase` command replays all the commits of a branch " +"at a newer location on the parent branch. We will cover the most common " +"scenarios that arise using it." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:741 +msgid "====== Create a branch" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:746 +msgid "" +"Let's say you want to make a change to FreeBSD's ls command to never, ever " +"do color. There are many reasons to do this, but this example will use that " +"as a baseline. The FreeBSD ls command changes from time to time, and you'll " +"need to cope with those changes. Fortunately, with Git rebase it usually is " +"automatic." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:768 +#, no-wrap +msgid "" +"% cd src\n" +"% git checkout main\n" +"% git checkout -b no-color-ls\n" +"% cd bin/ls\n" +"% vi ls.c # hack the changes in\n" +"% git diff # check the changes\n" +"diff --git a/bin/ls/ls.c b/bin/ls/ls.c\n" +"index 7378268867ef..cfc3f4342531 100644\n" +"--- a/bin/ls/ls.c\n" +"+++ b/bin/ls/ls.c\n" +"@@ -66,6 +66,7 @@ __FBSDID(\"$FreeBSD$\");\n" +" #include <stdlib.h>\n" +" #include <string.h>\n" +" #include <unistd.h>\n" +"+#undef COLORLS\n" +" #ifdef COLORLS\n" +" #include <termcap.h>\n" +" #include <signal.h>\n" +"% # these look good, make the commit...\n" +"% git commit ls.c\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:775 +msgid "" +"The commit will pop you into an editor to describe what you've done. Once " +"you enter that, you have your own **local** branch in the Git repo. Build " +"and install it like you normally would, following the directions in the " +"handbook. Git differs from other version control systems in that you have " +"to tell it explicitly which files to commit. I have opted to do it on the " +"commit command line, but you can also do it with `git add` which many of the " +"more in depth tutorials cover." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:777 +msgid "====== Time to update" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:782 +msgid "" +"When it is time to bring in a new version, it is almost the same as w/o the " +"branches. You would update like you would above, but there is one extra " +"command before you update, and one after. The following assumes you are " +"starting with an unmodified tree. It is important to start rebasing " +"operations with a clean tree (Git requires this)." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:788 +#, no-wrap +msgid "" +"% git checkout main\n" +"% git pull --ff-only\n" +"% git rebase -i main no-color-ls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:793 +msgid "" +"This will bring up an editor that lists all the commits in it. For this " +"example, do not change it at all. This is typically what you are doing " +"while updating the baseline (though you also use the Git rebase command to " +"curate the commits you have in the branch)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:795 +msgid "" +"Once you are done with the above, you have to move the commits to ls.c " +"forward from the old version of FreeBSD to the newer one." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:802 +msgid "" +"Sometimes there are merge conflicts. That is OK. Do not panic. Instead, " +"handle them the same as any other merge conflicts. To keep it simple, I " +"will just describe a common issue that may arise. A pointer to a more " +"complete treatment can be found at the end of this section." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:805 +msgid "" +"Let's say the includes changes upstream in a radical shift to terminfo as " +"well as a name change for the option. When you updated, you might see " +"something like this:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:815 +#, no-wrap +msgid "" +"Auto-merging bin/ls/ls.c\n" +"CONFLICT (content): Merge conflict in bin/ls/ls.c\n" +"error: could not apply 646e0f9cda11... no color ls\n" +"Resolve all conflicts manually, mark them as resolved with\n" +"\"git add/rm <conflicted_files>\", then run \"git rebase --continue\".\n" +"You can instead skip this commit: run \"git rebase --skip\".\n" +"To abort and get back to the state before \"git rebase\", run \"git rebase --abort\".\n" +"Could not apply 646e0f9cda11... no color ls\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:818 +msgid "" +"which looks scary. If you bring up an editor, you will see it is a typical " +"3-way merge conflict resolution that you may be familiar with from other " +"source code systems (the rest of ls.c has been omitted):" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:827 +#, no-wrap +msgid "" +" <<<<<<< HEAD\n" +" #ifdef COLORLS_NEW\n" +" #include <terminfo.h>\n" +" =======\n" +" #undef COLORLS\n" +" #ifdef COLORLS\n" +" #include <termcap.h>\n" +" >>>>>>> 646e0f9cda11... no color ls\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:831 +#, no-wrap +msgid "" +"The new code is first, and your code is second.\n" +"The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:835 +msgid "#undef COLORLS_NEW #ifdef COLORLS_NEW #include <terminfo.h>" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:839 +#, no-wrap +msgid "" +"save the file.\n" +"The rebase was interrupted, so you have to complete it:\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:842 +msgid "% git add ls.c % git rebase --continue" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:847 +#, no-wrap +msgid "" +"which tells Git that ls.c has been fixed and to continue the rebase operation.\n" +"Since there was a conflict, you will get kicked into the editor to update the commit message if necessary.\n" +"If the commit message is still accurate, just exit the editor.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:852 +#, no-wrap +msgid "" +"If you get stuck during the rebase, do not panic.\n" +"git rebase --abort will take you back to a clean slate.\n" +"It is important, though, to start with an unmodified tree.\n" +"An aside: The above mentioned `git reflog` comes in handy here, as it will have a list of all the (intermediate) commits that you can view or inspect or cherry-pick.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:855 +#, no-wrap +msgid "" +"For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment.\n" +"It is a good resource for issues that arise occasionally but are too obscure for this guide.\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:856 +#, no-wrap +msgid "Switching to a Different FreeBSD Branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:860 +msgid "" +"If you wish to shift from stable/12 to the current branch. If you have a " +"deep clone, the following will suffice: [source,shell]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:863 +msgid "% git checkout main % # build and install here..." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:869 +#, no-wrap +msgid "" +"If you have a local branch, though, there are one or two caveats.\n" +"First, rebase will rewrite history, so you will likely want to do something to save it.\n" +"Second, jumping branches tends to cause more conflicts.\n" +"If we pretend the example above was relative to stable/12, then to move to `main`, I'd suggest the following:\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:873 +#, no-wrap +msgid "" +"% git checkout no-color-ls\n" +"% git checkout -b no-color-ls-stable-12 # create another name for this branch\n" +"% git rebase -i stable/12 no-color-ls --onto main\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:880 +#, no-wrap +msgid "" +"What the above does is checkout no-color-ls.\n" +"Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it.\n" +"Then you rebase onto the `main` branch.\n" +"This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will\n" +"replay them onto the `main` branch creating a new no-color-ls branch there (which is why I had you create a place holder name).\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:882 +#, no-wrap +msgid "[[mfc-with-git]]\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:882 +#, no-wrap +msgid "MFC (Merge From Current) Procedures" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:883 +#, no-wrap +msgid "Summary" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:887 +msgid "" +"MFC workflow can be summarized as `git cherry-pick -x` plus `git commit --" +"amend` to adjust the commit message. For multiple commits, use `git rebase -" +"i` to squash them together and edit the commit message." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:888 +#, no-wrap +msgid "Single commit MFC" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:891 +#: documentation/content/en/articles/committers-guide/_index.adoc:931 +#: documentation/content/en/articles/committers-guide/_index.adoc:967 +#: documentation/content/en/articles/committers-guide/_index.adoc:1083 +#: documentation/content/en/articles/committers-guide/_index.adoc:1096 +#: documentation/content/en/articles/committers-guide/_index.adoc:1123 +#: documentation/content/en/articles/committers-guide/_index.adoc:1135 +#: documentation/content/en/articles/committers-guide/_index.adoc:1201 +#: documentation/content/en/articles/committers-guide/_index.adoc:1219 +#: documentation/content/en/articles/committers-guide/_index.adoc:1241 +#: documentation/content/en/articles/committers-guide/_index.adoc:1259 +#: documentation/content/en/articles/committers-guide/_index.adoc:1279 +#: documentation/content/en/articles/committers-guide/_index.adoc:1294 +#: documentation/content/en/articles/committers-guide/_index.adoc:1313 +#: documentation/content/en/articles/committers-guide/_index.adoc:1345 +#: documentation/content/en/articles/committers-guide/_index.adoc:1392 +#: documentation/content/en/articles/committers-guide/_index.adoc:1456 +msgid "[source,shell]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:894 +msgid "% git checkout stable/X % git cherry-pick -x $HASH --edit" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:898 +#, no-wrap +msgid "" +"For MFC commits, for example a vendor import, you would need to specify one parent for cherry-pick purposes.\n" +"Normally, that would be the \"first parent\" of the branch you are cherry-picking from, so:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:900 +#: documentation/content/en/articles/committers-guide/_index.adoc:921 +#: documentation/content/en/articles/committers-guide/_index.adoc:944 +#: documentation/content/en/articles/committers-guide/_index.adoc:955 +#: documentation/content/en/articles/committers-guide/_index.adoc:1173 +#: documentation/content/en/articles/committers-guide/_index.adoc:1267 +#: documentation/content/en/articles/committers-guide/_index.adoc:1352 +#: documentation/content/en/articles/committers-guide/_index.adoc:1364 +#: documentation/content/en/articles/committers-guide/_index.adoc:1376 +#: documentation/content/en/articles/committers-guide/_index.adoc:1402 +#: documentation/content/en/articles/committers-guide/_index.adoc:1414 +#: documentation/content/en/articles/committers-guide/_index.adoc:1421 +#: documentation/content/en/articles/committers-guide/_index.adoc:1463 +#: documentation/content/en/articles/committers-guide/_index.adoc:1497 +#: documentation/content/en/articles/committers-guide/_index.adoc:1504 +#: documentation/content/en/articles/committers-guide/_index.adoc:1513 +#: documentation/content/en/articles/committers-guide/_index.adoc:1542 +#: documentation/content/en/articles/committers-guide/_index.adoc:1558 +#: documentation/content/en/articles/committers-guide/_index.adoc:1591 +#: documentation/content/en/articles/committers-guide/_index.adoc:1612 +#: documentation/content/en/articles/committers-guide/_index.adoc:1643 +#: documentation/content/en/articles/committers-guide/_index.adoc:1655 +#: documentation/content/en/articles/committers-guide/_index.adoc:1686 +#: documentation/content/en/articles/committers-guide/_index.adoc:1695 +#: documentation/content/en/articles/committers-guide/_index.adoc:1705 +#: documentation/content/en/articles/committers-guide/_index.adoc:1721 +#: documentation/content/en/articles/committers-guide/_index.adoc:1737 +#: documentation/content/en/articles/committers-guide/_index.adoc:1748 +#: documentation/content/en/articles/committers-guide/_index.adoc:1755 +#: documentation/content/en/articles/committers-guide/_index.adoc:1768 +#: documentation/content/en/articles/committers-guide/_index.adoc:1788 +#: documentation/content/en/articles/committers-guide/_index.adoc:1802 +#: documentation/content/en/articles/committers-guide/_index.adoc:1818 +#: documentation/content/en/articles/committers-guide/_index.adoc:1830 +#: documentation/content/en/articles/committers-guide/_index.adoc:1849 +#: documentation/content/en/articles/committers-guide/_index.adoc:1860 +#: documentation/content/en/articles/committers-guide/_index.adoc:1870 +#: documentation/content/en/articles/committers-guide/_index.adoc:1908 +#: documentation/content/en/articles/committers-guide/_index.adoc:1916 +#: documentation/content/en/articles/committers-guide/_index.adoc:1927 +#: documentation/content/en/articles/committers-guide/_index.adoc:1948 +#: documentation/content/en/articles/committers-guide/_index.adoc:2008 +#, no-wrap +msgid "[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:903 +msgid "% git checkout stable/X % git cherry-pick -x $HASH -m 1 --edit" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:906 +#, no-wrap +msgid "If things go wrong, you'll either need to abort the cherry-pick with `git cherry-pick --abort` or fix it up and do a `git cherry-pick --continue`.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:909 +#, no-wrap +msgid "" +"Once the cherry-pick is finished, push with `git push`.\n" +"If you get an error due to losing the commit race, use `git pull --rebase` and try to push again.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:910 +#, no-wrap +msgid "MFC to RELENG branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:914 +msgid "" +"MFCs to branches that require approval require a bit more care. The process " +"is the same for either a typical merge or an exceptional direct commit." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:919 +#, no-wrap +msgid "" +"* Merge or direct commit to the appropriate `stable/X` branch first before merging to the `releng/X.Y` branch.\n" +"* Use the hash that's in the `stable/X` branch for the MFC to `releng/X.Y` branch.\n" +"* Leave both \"cherry picked from\" lines in the commit message.\n" +"* Be sure to add the `Approved by:` line when you are in the editor.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:924 +msgid "% git checkout releng/13.0 % git cherry-pick -x $HASH --edit" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:927 +#, no-wrap +msgid "If you forget to to add the `Approved by:` line, you can do a `git commit --amend` to edit the commit message before you push the change.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:928 +#, no-wrap +msgid "Multiple commit MFC" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:939 +msgid "" +"% git checkout -b tmp-branch stable/X % for h in $HASH_LIST; do git cherry-" +"pick -x $h; done % git rebase -i stable/X # mark each of the commits after " +"the first as 'squash' # Update the commit message to reflect all elements of " +"commit, if necessary. # Be sure to retain the \"cherry picked from\" " +"lines. % git push freebsd HEAD:stable/X" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:942 +#, no-wrap +msgid "If the push fails due to losing the commit race, rebase and try again:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:950 +msgid "" +"% git checkout stable/X % git pull % git checkout tmp-branch % git rebase " +"stable/X % git push freebsd HEAD:stable/X" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:953 +#, no-wrap +msgid "Once the MFC is complete, you can delete the temporary branch:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:958 +msgid "% git checkout stable/X % git branch -d tmp-branch" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:960 +#, no-wrap +msgid "MFC a vendor import" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:965 +msgid "" +"Vendor imports are the only thing in the tree that creates a merge commit in " +"the `main` branch. Cherry picking merge commits into stable/XX presents an " +"additional difficulty because there are two parents for a merge commit. " +"Generally, you'll want the first parent's diff since that's the diff to " +"`main` (though there may be some exceptions)." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:969 +msgid "% git cherry-pick -x -m 1 $HASH" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:972 +#, no-wrap +msgid "" +"is typically what you want.\n" +"This will tell cherry-pick to apply the correct diff.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:977 +#, no-wrap +msgid "" +"There are some, hopefully, rare cases where it's possible that the `main` branch was merged backwards by the conversion script.\n" +"Should that be the case (and we've not found any yet), you'd change the above to `-m 2` to pickup the proper parent.\n" +"Just do:\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:980 +msgid "% git cherry-pick --abort % git cherry-pick -x -m 2 $HASH" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:982 +#, no-wrap +msgid "to do that. The `--abort` will cleanup the failed first attempt.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:983 +#, no-wrap +msgid "Redoing a MFC" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:988 +msgid "" +"If you do a MFC, and it goes horribly wrong and you want to start over, then " +"the easiest way is to use `git reset --hard` like so: [source,shell]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:990 +msgid "% git reset --hard freebsd/stable/12" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:993 +#, no-wrap +msgid "" +"though if you have some revs you want to keep, and others you don't,\n" +"using `git rebase -i` is better.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:994 +#, no-wrap +msgid "Considerations when MFCing" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:997 +msgid "" +"When committing source commits to stable and releng branches, we have the " +"following goals:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1001 +#, no-wrap +msgid "" +"* Clearly mark direct commits distinct from commits that land a change from another branch.\n" +"* Avoid introducing known breakage into stable and releng branches.\n" +"* Allow developers to determine which changes have or have not been landed from one branch to another.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1003 +#, no-wrap +msgid "With Subversion, we used the following practices to achieve these goals:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1007 +#, no-wrap +msgid "" +"* Using `MFC` and `MFS` tags to mark commits that merged changes from another branch.\n" +"* Squashing fixup commits into the main commit when merging a change.\n" +"* Recording mergeinfo so that `svn mergeinfo --show-revs` worked.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1011 +#, no-wrap +msgid "" +"With Git, we will need to use different strategies to achieve the same goals.\n" +"This document aims to define best practices when merging source commits using Git that achieve these goals.\n" +"In general, we aim to use Git's native support to achieve these goals rather than enforcing practices built on Subversion's model.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1014 +#, no-wrap +msgid "" +"One general note: due to technical differences with Git, we will not be using Git \"merge commits\" (created via `git merge`) in stable or releng branches.\n" +"Instead, when this document refers to \"merge commits\", it means a commit originally made to `main` that is replicated or \"landed\" to a stable branch, or a commit from a stable branch that is replicated to a releng branch with some variation of `git cherry-pick`.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1015 +#, no-wrap +msgid "Finding Eligible Hashes to MFC" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1021 +msgid "" +"Git provides some built-in support for this via the `git cherry` and `git " +"log --cherry` commands. These commands compare the raw diffs of commits " +"(but not other metadata such as log messages) to determine if two commits " +"are identical. This works well when each commit from `main` is landed as a " +"single commit to a stable branch, but it falls over if multiple commits from " +"`main` are squashed together as a single commit to a stable branch. The " +"project makes extensive use of `git cherry-pick -x` with all lines preserved " +"to work around these difficulties and is working on automated tooling to " +"take advantage of this." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1022 +#, no-wrap +msgid "Commit message standards" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1023 +#, no-wrap +msgid "Marking MFCs" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1026 +msgid "The project has adopted the following practice for marking MFCs:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1028 +#, no-wrap +msgid "* Use the `-x` flag with `git cherry-pick`. This adds a line to the commit message that includes the hash of the original commit when merging. Since it is added by Git directly, committers do not have to manually edit the commit log when merging.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1030 +#, no-wrap +msgid "When merging multiple commits, keep all the \"cherry picked from\" lines.\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1031 +#, no-wrap +msgid "Trim Metadata?" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1035 +msgid "" +"One area that was not clearly documented with Subversion (or even CVS) is " +"how to format metadata in log messages for MFC commits. Should it include " +"the metadata from the original commit unchanged, or should it be altered to " +"reflect information about the MFC commit itself?" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1044 +msgid "" +"Historical practice has varied, though some of the variance is by field. " +"For example, MFCs that are relevant to a PR generally include the PR field " +"in the MFC so that MFC commits are included in the bug tracker's audit " +"trail. Other fields are less clear. For example, Phabricator shows the " +"diff of the last commit tagged to a review, so including Phabricator URLs " +"replaces the main commit with the landed commits. The list of reviewers is " +"also not clear. If a reviewer has approved a change to `main`, does that " +"mean they have approved the MFC commit? Is that true if it's identical code " +"only, or with merely trivial rework? It's clearly not true for more " +"extensive reworks. Even for identical code what if the commit doesn't " +"conflict but introduces an ABI change? A reviewer may have ok'd a commit for " +"`main` due to the ABI breakage but may not approve of merging the same " +"commit as-is. One will have to use one's best judgment until clear " +"guidelines can be agreed upon." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1048 +msgid "" +"For MFCs regulated by re@, new metadata fields are added, such as the " +"Approved by tag for approved commits. This new metadata will have to be " +"added via `git commit --amend` or similar after the original commit has been " +"reviewed and approved. We may also want to reserve some metadata fields in " +"MFC commits such as Phabricator URLs for use by re@ in the future." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1051 +msgid "" +"Preserving existing metadata provides a very simple workflow. Developers " +"use `git cherry-pick -x` without having to edit the log message." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1054 +msgid "" +"If instead we choose to adjust metadata in MFCs, developers will have to " +"edit log messages explicitly via the use of `git cherry-pick --edit` or `git " +"commit --amend`. However, as compared to svn, at least the existing commit " +"message can be pre-populated and metadata fields can be added or removed " +"without having to re-enter the entire commit message." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1056 +msgid "" +"The bottom line is that developers will likely need to curate their commit " +"message for MFCs that are non-trivial." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1058 +msgid "[[vendor-import-git]]" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1058 +#, no-wrap +msgid "Vendor Imports with Git" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1061 +msgid "This section describes the vendor import procedure with Git in detail." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1062 +#, no-wrap +msgid "Branch naming convention" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1065 +msgid "" +"All vendor branches and tags start with `vendor/`. These branches and tags " +"are visible by default." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1071 +msgid "" +"[NOTE] ==== This chapter follows the convention that the `freebsd` origin is " +"the origin name for the official FreeBSD Git repository. If you use a " +"different convention, replace `freebsd` with the name you use instead in the " +"examples below. ====" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1074 +msgid "" +"We will explore an example for updating NetBSD's mtree that is in our tree. " +"The vendor branch for this is `vendor/NetBSD/mtree`." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1075 +#, no-wrap +msgid "Updating an old vendor import" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1081 +msgid "" +"The vendor trees usually have only the subset of the third-party software " +"that is appropriate to FreeBSD. These trees are usually tiny in comparison " +"to the FreeBSD tree. Git worktrees are thus quite small and fast and the " +"preferred method to use. Make sure that whatever directory you choose below " +"(the `../mtree`) does not currently exist." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1085 +msgid "% git worktree add ../mtree vendor/NetBSD/mtree" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1087 +#, no-wrap +msgid "Update the Sources in the Vendor Branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1090 +msgid "" +"Prepare a full, clean tree of the vendor sources. Import everything but " +"merge only what is needed." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1094 +msgid "" +"This example assumes the NetBSD source is checked out from their GitHub " +"mirror in `~/git/NetBSD`. Note that \"upstream\" might have added or " +"removed files, so we want to make sure deletions are propagated as well. " +"package:net/rsync[] is commonly installed, so I'll use that." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1108 +#, no-wrap +msgid "" +"% cd ../mtree\n" +"% rsync -va --del --exclude=\".git\" ~/git/NetBSD/usr.sbin/mtree/ .\n" +"% git add -A\n" +"% git status\n" +"...\n" +"% git diff --staged\n" +"...\n" +"% git commit -m \"Vendor import of NetBSD's mtree at 2020-12-11\"\n" +"[vendor/NetBSD/mtree 8e7aa25fcf1] Vendor import of NetBSD's mtree at 2020-12-11\n" +" 7 files changed, 114 insertions(+), 82 deletions(-)\n" +"% git tag -a vendor/NetBSD/mtree/20201211\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1112 +#, no-wrap +msgid "" +"Note: I run the `git diff` and `git status` commands to make sure nothing weird was present.\n" +"Also I used `-m` to illustrate, but you should compose a proper message in an editor (using a commit message template).\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1117 +#, no-wrap +msgid "" +"It is also important to create an annotated tag using `git tag -a`, otherwise the push will be rejected.\n" +"Only annotated tags are allowed to be pushed.\n" +"The annotated tag gives you a chance to enter a commit message.\n" +"Enter the version you are importing, along with any salient new features or fixes in that version.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1118 +#, no-wrap +msgid "Updating the FreeBSD Copy" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1121 +msgid "At this point you can push the import to `vendor` into our repo." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1125 +msgid "% git push --follow-tags freebsd vendor/NetBSD/mtree" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1128 +#, no-wrap +msgid "`--follow-tags` tells `git push` to also push tags associated with the locally committed revision.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1129 +#, no-wrap +msgid "Updating the FreeBSD source tree" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1133 +msgid "" +"Now you need to update the mtree in FreeBSD. The sources live in `contrib/" +"mtree` since it is upstream software." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1138 +msgid "% cd ../src % git subtree merge -P contrib/mtree vendor/NetBSD/mtree" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1143 +#, no-wrap +msgid "" +"This would generate a subtree merge commit of `contrib/mtree` against the local `vendor/NetBSD/mtree` branch.\n" +"If there were conflicts, you would need to fix them before committing.\n" +"Include details about the changes being merged in the merge commit message.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1144 +#, no-wrap +msgid "Rebasing your change against latest FreeBSD source tree" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1147 +msgid "" +"Because the current policy recommends against using merges, if the upstream " +"FreeBSD `main` moved forward before you get a chance to push, you would have " +"to redo the merge." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1150 +msgid "" +"Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a " +"merge commit **as a merge commit**, so instead of that you would have to " +"recreate the commit." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1152 +msgid "" +"The following steps should be taken to easily recreate the merge commit as " +"if `git rebase --merge-commits` worked properly:" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1169 +#, no-wrap +msgid "" +"* cd to the top of the repo\n" +"* Create a side branch `XXX` with the **contents** of the merged tree.\n" +"* Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch.\n" +"** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare.\n" +"** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed)\n" +"* checkout `main`\n" +"* create a branch `YYY` (allows for easier unwinding if things go wrong)\n" +"* Re-do the subtree merge\n" +"* Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it.\n" +"** The trailing `.` is important, as is being at the top level of the repo.\n" +"** Rather than switching branches to XXX, it splats the contents of XXX on top of the repo\n" +"* Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch).\n" +"* Make sure the branches are the same.\n" +"* Do whatever review you need, including having others check it out if you think that's needed.\n" +"* Push the commit, if you 'lost the race' again, just redo these steps again (see below for a recipe)\n" +"* Delete the branches once the commit is upstream. They are throw-a-way.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1171 +#, no-wrap +msgid "The commands one would use, following the above example of mtree, would be like so (the `#` starts a comment to help link commands to descriptions above):\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1184 +#, no-wrap +msgid "" +"% cd ../src\t\t\t# CD to top of tree\n" +"% git checkout -b XXX\t\t# create new throw-away XXX branch for merge\n" +"% git fetch freebsd\t\t# Get changes from upstream from upstream\n" +"% git merge freebsd/main\t# Merge the changes and resolve conflicts\n" +"% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo\n" +"% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge\n" +"% git checkout XXX .\t\t# XXX branch has the conflict resolution\n" +"% git commit -c XXX~1\t\t# -c reuses the commit message from commit before rebase\n" +"% git diff XXX YYY\t\t# Should be empty\n" +"% git show YYY\t\t\t# Should only have changes you want, and be a merge commit from vendor branch\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1188 +#, no-wrap +msgid "" +"Note: if things go wrong with the commit, you can reset the `YYY` branch by reissuing the checkout command that created it with -B to start over:\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1190 +msgid "" +"% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if " +"starting over is just going to be easier" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1192 +#, no-wrap +msgid "Pushing the changes" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1197 +msgid "" +"Once you think you have a set of changes that are good, you can push it to a " +"fork off GitHub or GitLab for others to review. One nice thing about Git is " +"that it allows you to publish rough drafts of your work for others to " +"review. While Phabricator is good for content review, publishing the " +"updated vendor branch and merge commits lets others check the details as " +"they will eventually appear in the repository." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1199 +msgid "" +"After review, when you are sure it is a good change, you can push it to the " +"FreeBSD repo:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1205 +msgid "" +"% git push freebsd YYY:main\t# put the commit on upstream's 'main' branch % " +"git branch -D XXX\t\t# Throw away the throw-a-way branches. % git branch -D " +"YYY" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1212 +#, no-wrap +msgid "" +"Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine.\n" +"If you use such names for other work, then you'll need to pick different names, or risk losing the other work.\n" +"There is nothing magic about these names.\n" +"Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above.\n" +"Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1213 +#, no-wrap +msgid "How to redo things if need be" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1217 +msgid "" +"If you've tried to do the push in the previous section and it fails, then " +"you should do the following to 'redo' things. This sequence keeps the " +"commit with the commit message always at XXX~1 to make committing easier." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1226 +msgid "" +"% git checkout -B XXX YYY\t# recreate that throw-away-branch XXX and switch " +"to it % git merge freebsd/main\t# Merge the changes and resolve conflicts % " +"git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for " +"redo % git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree " +"merge % git checkout XXX .\t\t# XXX branch has the conflict resolution % git " +"commit -c XXX~1\t\t# -c reuses the commit message from commit before rebase" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1229 +#, no-wrap +msgid "Then go check it out as above and push as above when ready.\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1230 +#, no-wrap +msgid "Creating a new vendor branch" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1237 +msgid "" +"There are a number of ways to create a new vendor branch. The recommended " +"way is to create a new repository and then merge that with FreeBSD. If one " +"is importing `glorbnitz` into the FreeBSD tree, release 3.1415. For the " +"sake of simplicity, we will not trim this release. It is a simple user " +"command that puts the nitz device into different magical glorb states and is " +"small enough trimming will not save much." +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1238 +#, no-wrap +msgid "Create the repo" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1247 +msgid "" +"% cd /some/where % mkdir glorbnitz % cd glorbnitz % git init % git checkout -" +"b vendor/glorbnitz" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1250 +#, no-wrap +msgid "At this point, you have a new repo, where all new commits will go on the `vendor/glorbnitz` branch.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1252 +#, no-wrap +msgid "Git experts can also do this right in their FreeBSD clone, using `git checkout --orphan vendor/glorbnitz` if they are more comfortable with that.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1253 +#, no-wrap +msgid "Copy the sources in" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1257 +msgid "" +"Since this is a new import, you can just cp the sources in, or use tar or " +"even rsync as shown above. And we will add everything, assuming no dot " +"files." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1262 +msgid "% cp -r ~/glorbnitz/* . % git add *" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1265 +#, no-wrap +msgid "At this point, you should have a pristine copy of glorbnitz ready to commit.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1269 +msgid "% git commit -m \"Import GlorbNitz frobnosticator revision 3.1415\"" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1273 +#, no-wrap +msgid "" +"As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it.\n" +"Not everybody will know so, for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1274 +#, no-wrap +msgid "Now import it into our repository" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1277 +msgid "Now you need to import the branch into our repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1283 +msgid "" +"% cd /path/to/freebsd/repo/src % git remote add glorbnitz /some/where/" +"glorbnitz % git fetch glorbnitz vendor/glorbnitz" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1288 +#, no-wrap +msgid "" +"Note the vendor/glorbnitz branch is in the repo. At this point the `/some/where/glorbnitz` can be deleted, if you like.\n" +"It was only a means to an end.\n" +"// perhaps the real treasure was the friends it made along the way...\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1289 +#, no-wrap +msgid "Tag and push" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1292 +msgid "" +"Steps from here on out are much the same as they are in the case of updating " +"a vendor branch, though without the updating the vendor branch step." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1300 +msgid "" +"% git worktree add ../glorbnitz vendor/glorbnitz % cd ../glorbnitz % git tag " +"--annotate vendor/glorbnitz/3.1415 # Make sure the commit is good with \"git " +"show\" % git push --follow-tags freebsd vendor/glorbnitz" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1303 +#, no-wrap +msgid "By 'good' we mean:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1309 +#, no-wrap +msgid "" +". All the right files are present\n" +". None of the wrong files are present\n" +". The vendor branch points at something sensible\n" +". The tag looks good, and is annotated\n" +". The commit message for the tag has a quick summary of what's new since the last tag\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1310 +#, no-wrap +msgid "Time to finally merge it into the base tree" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1319 +#, no-wrap +msgid "" +"% cd ../src\n" +"% git subtree add -P contrib/glorbnitz vendor/glorbnitz\n" +"# Make sure the commit is good with \"git show\"\n" +"% git commit --amend # one last sanity check on commit message\n" +"% git push freebsd\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1322 +#, no-wrap +msgid "Here 'good' means:\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1327 +#, no-wrap +msgid "" +". All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.\n" +". No other changes are in the tree.\n" +". The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.\n" +". UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1333 +#, no-wrap +msgid "" +"[NOTE]\n" +"====\n" +"This hasn't connected `glorbnitz` to the build yet.\n" +"How so do that is specific to the software being imported and is beyond the scope of this tutorial.\n" +"====\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1334 +#, no-wrap +msgid "Keeping current" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1340 +msgid "" +"So, time passes. It's time now to update the tree for the latest changes " +"upstream. When you checkout `main` make sure that you have no diffs. It's " +"a lot easier to commit those to a branch (or use `git stash`) before doing " +"the following." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1343 +msgid "" +"If you are used to `git pull`, we strongly recommend using the `--ff-only` " +"option, and further setting it as the default option. Alternatively, `git " +"pull --rebase` is useful if you have changes staged in the `main` branch." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1347 +msgid "% git config --global pull.ff only" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1350 +#, no-wrap +msgid "You may need to omit the --global if you want this setting to apply to only this repository.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1356 +msgid "% cd freebsd-src % git checkout main % git pull (--ff-only|--rebase)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1360 +#, no-wrap +msgid "" +"There is a common trap, that the combination command `git pull` will try to perform a merge, which would sometimes creates a merge commit that didn't exist before.\n" +"This can be harder to recover from.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1362 +#, no-wrap +msgid "The longer form is also recommended.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1369 +msgid "" +"% cd freebsd-src % git checkout main % git fetch freebsd % git merge --ff-" +"only freebsd/main" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1374 +#, no-wrap +msgid "" +"These commands reset your tree to the `main` branch, and then update it from where you pulled the tree from originally.\n" +"It's important to switch to `main` before doing this so it moves forward.\n" +"Now, it's time to move the changes forward:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1378 +msgid "% git rebase -i main working" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1385 +#, no-wrap +msgid "" +"This will bring up an interactive screen to change the defaults.\n" +"For now, just exit the editor.\n" +"Everything should just apply.\n" +"If not, then you'll need to resolve the diffs.\n" +"https://docs.github.com/en/free-pro-team@latest/github/using-git/resolving-merge-conflicts-after-a-git-rebase[This github document] can help you navigate this process.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1387 +#, no-wrap +msgid "[[git-push-upstream]]\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1387 +#, no-wrap +msgid "Time to push changes upstream" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1390 +msgid "" +"First, ensure that the push URL is properly configured for the upstream " +"repository." +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1394 +msgid "" +"% git remote set-url --push freebsd ssh://git@gitrepo.freebsd.org/src.git" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1398 +#, no-wrap +msgid "" +"Then, verify that user name and email are configured right.\n" +"We require that they exactly match the passwd entry in FreeBSD cluster.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1400 +#, no-wrap +msgid "Use\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1404 +msgid "freefall% gen-gitconfig.sh" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1407 +#, no-wrap +msgid "on freefall.freebsd.org to get a recipe that you can use directly, assuming /usr/local/bin is in the PATH.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1412 +#, no-wrap +msgid "" +"The below command merges the `working` branch into the upstream `main` branch.\n" +"It's important that you curate your changes to be just like you want them in the FreeBSD source repo before doing this.\n" +"This syntax pushes the `working` branch to `main`, moving the `main` branch forward.\n" +"You will only be able to do this if this results in a linear change to `main` (e.g. no merges).\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1416 +msgid "% git push freebsd working:main" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1419 +#, no-wrap +msgid "If your push is rejected due to losing a commit race, rebase your branch before trying again:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1426 +msgid "" +"% git checkout working % git fetch freebsd % git rebase freebsd/main % git " +"push freebsd working:main" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1429 +#, no-wrap +msgid "[[git-push-upstream-alt]]\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1429 +#, no-wrap +msgid "Time to push changes upstream (alternative)" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1435 +msgid "" +"Some people find it easier to merge their changes to their local `main` " +"before pushing to the remote repository. Also, `git arc stage` moves " +"changes from a branch to the local `main` when you need to do a subset of a " +"branch. The instructions are similar to the prior section: [source,shell]" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1439 +msgid "% git checkout main % git merge --ff-only `working` % git push freebsd" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1443 +#, no-wrap +msgid "" +"If you lose the race, then try again with\n" +"[source,shell]\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1446 +msgid "% git pull --rebase % git push freebsd" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1449 +#, no-wrap +msgid "" +"These commands will fetch the most recent `freebsd/main` and then rebase the local `main` changes on top of that, which is what you want when you lose the commit race.\n" +"Note: merging vendor branch commits will not work with this technique.\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1450 +#, no-wrap +msgid "Finding the Subversion Revision" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1454 +msgid "" +"You'll need to make sure that you've fetched the notes (see the <<git-mini-" +"daily-use>> for details). Once you have these, notes will show up in the " +"git log command like so:" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1458 +msgid "% git log" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1461 +#, no-wrap +msgid "If you have a specific version in mind, you can use this construct:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1465 +msgid "% git log --grep revision=XXXX" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1469 +#, no-wrap +msgid "" +"to find the specific revision.\n" +"The hex number after 'commit' is the hash you can use to refer to this commit.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1471 +#, no-wrap +msgid "[[git-faq]]\n" +msgstr "" + +#. type: Title === +#: documentation/content/en/articles/committers-guide/_index.adoc:1471 +#, no-wrap +msgid "Git FAQ" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1474 +msgid "" +"This section provides a number of targeted answers to questions that are " +"likely to come up often for users and developers." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1480 +msgid "" +"[NOTE] ==== We use the common convention of having the origin for the " +"FreeBSD repository being 'freebsd' rather than the default 'origin' to allow " +"people to use that for their own development and to minimize \"whoops\" " +"pushes to the wrong repository. ====" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1481 +#, no-wrap +msgid "Users" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1483 +#, no-wrap +msgid "How do I track -current and -stable with only one copy of the repository?" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1488 +#, no-wrap +msgid "" +"**Q:** Although disk space is not a huge issue, it's more efficient to use only one copy of the repository.\n" +"With SVN mirroring, I could checkout multiple trees from the same repository.\n" +"How do I do this with Git?\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1492 +#, no-wrap +msgid "" +"**A:** You can use Git worktrees.\n" +"There's a number of ways to do this, but the simplest way is to use a clone to track -current, and a worktree to track stable releases.\n" +"While using a 'bare repository' has been put forward as a way to cope, it's more complicated and will not be documented here.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1495 +#, no-wrap +msgid "" +"First, you need to clone the FreeBSD repository, shown here cloning into `freebsd-current` to reduce confusion.\n" +"$URL is whatever mirror works best for you:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1499 +msgid "" +"% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/" +"notes/*' $URL freebsd-current" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1502 +#, no-wrap +msgid "then once that's cloned, you can simply create a worktree from it:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1507 +msgid "% cd freebsd-current % git worktree add ../freebsd-stable-12 stable/12" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1511 +#, no-wrap +msgid "" +"this will checkout `stable/12` into a directory named `freebsd-stable-12` that's a peer to the `freebsd-current` directory.\n" +"Once created, it's updated very similarly to how you might expect:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1521 +msgid "" +"% cd freebsd-current % git checkout main % git pull --ff-only # changes from " +"upstream now local and current tree updated % cd ../freebsd-stable-12 % git " +"merge --ff-only freebsd/stable/12 # now your stable/12 is up to date too" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1524 +#, no-wrap +msgid "I recommend using `--ff-only` because it's safer and you avoid accidentally getting into a 'merge nightmare' where you have an extra change in your tree, forcing a complicated merge rather than a simple one.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1526 +#, no-wrap +msgid "Here's https://adventurist.me/posts/00296[a good writeup] that goes into more detail.\n" +msgstr "" + +#. type: Title ==== +#: documentation/content/en/articles/committers-guide/_index.adoc:1527 +#, no-wrap +msgid "Developers" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1529 +#, no-wrap +msgid "Ooops! I committed to `main`, instead of another branch." +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1532 +#, no-wrap +msgid "**Q:** From time to time, I goof up and mistakenly commit to the `main` branch. What do I do?\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1534 +#, no-wrap +msgid "**A:** First, don't panic.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1538 +#, no-wrap +msgid "" +"Second, don't push.\n" +"In fact, you can fix almost anything if you haven't pushed.\n" +"All the answers in this section assume no push has happened.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1540 +#, no-wrap +msgid "The following answer assumes you committed to `main` and want to create a branch called `issue`:\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1546 +#, no-wrap +msgid "" +"% git branch issue # Create the 'issue' branch\n" +"% git reset --hard freebsd/main # Reset 'main' back to the official tip\n" +"% git checkout issue # Back to where you were\n" +msgstr "" + +#. type: Title ===== +#: documentation/content/en/articles/committers-guide/_index.adoc:1548 +#, no-wrap +msgid "Ooops! I committed something to the wrong branch!" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1552 +#, no-wrap +msgid "" +"**Q:** I was working on feature on the `wilma` branch, but accidentally committed a change relevant to the `fred` branch in 'wilma'.\n" +"What do I do?\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1556 +#, no-wrap +msgid "" +"**A:** The answer is similar to the previous one, but with cherry picking.\n" +"This assumes there's only one commit on wilma, but will generalize to more complicated situations.\n" +"It also assumes that it's the last commit on wilma (hence using wilma in the `git cherry-pick` command), but that too can be generalized.\n" +msgstr "" + +#. type: Plain text +#: documentation/content/en/articles/committers-guide/_index.adoc:1564 +msgid "" +"# We're on branch wilma % git checkout fred\t\t# move to fred branch % git " +"cherry-pick wilma\t\t# copy the misplaced commit % git checkout wilma\t\t# " +"go back to wilma branch % git reset --hard HEAD^\t# move what wilma refers " +"to back 1 commit" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1568 +#, no-wrap +msgid "" +"Git experts would first rewind the wilma branch by 1 commit, switch over to fred and then use `git reflog` to see what that 1 deleted commit was and\n" +"cherry-pick it over.\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1570 +#, no-wrap +msgid "**Q:** But what if I want to commit a few changes to `main`, but keep the rest in `wilma` for some reason?\n" +msgstr "" + +#. type: delimited block . 4 +#: documentation/content/en/articles/committers-guide/_index.adoc:1576 +#, no-wrap +msgid "" +"**A:** The same technique above also works if you are wanting to 'land' parts of the branch you are working on into `main` before the rest of the branch is ready (say you noticed an unrelated typo, or fixed an incidental bug).\n" +"You can cherry pick those cha |