Index: en_US.ISO8859-1/articles/committers-guide/article.xml =================================================================== --- en_US.ISO8859-1/articles/committers-guide/article.xml +++ en_US.ISO8859-1/articles/committers-guide/article.xml @@ -1,6 +1,6 @@ ]> @@ -9,7 +9,7 @@ xml:lang="en"> - Committer's Guide + FreeBSD Committer's Guide The &os; Documentation Project @@ -35,6 +35,7 @@ 2015 2016 2017 + The &os; Documentation Project @@ -52,178 +53,771 @@ $FreeBSD$ - This document provides information for the &os; - 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. - - Almost all &os; 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 - for more information. - - This document may also be of interest to members of the - &os; community who want to learn more about how the project - works. + Welcome to &os;! This onboarding guide provides new &os; + committers, contributors, GSoC students, and other project + community members with the procedures, policies and tools + required to commit to the various &os; source repositories. + While not every section of this guide will apply to every new + community member, every project participant is encouraged to + grow their project participation in conjunction with the + growth of their technical abilities. Existing committers are + strongly encouraged to review this guide from time to time and + committers who would like to mentor a new committer should + refer to the New + Account Creation Procedure page for guidance. - - Administrative Details - - - - - - - - Login Methods - &man.ssh.1;, protocol 2 only - - - - Main Shell Host - freefall.FreeBSD.org - + + Benefits of &os; Project Participation - - src/ Subversion - Root - svn+ssh://repo.FreeBSD.org/base - (see also ). - + + Recognition - - doc/ Subversion - Root - svn+ssh://repo.FreeBSD.org/doc - (see also ). - + Recognition as an open source software contributor is the + longest lasting benefit of contributing to &os;. The &os; + project has brought together contributors from around the world + for over 20 years under three generations of leadership. &os; + is a complete operating system for various computing + architectures with a welcoming community that focuses on + tecnological innovation, flexibility and performance. + Additional benefits of contributing to &os; include: + - - ports/ Subversion - Root + + FreeBSD Mall Discs + + &os; committers can get a free 4-CD or DVD set at + conferences from + &os; Mall, + Inc.. + + + + Freenode <acronym>IRC</acronym> cloked hostmasks + + In addition, developers may request a cloaked hostmask + for their account on the Freenode IRC network in the form + of + freebsd/developer/freefall + name or + freebsd/developer/NickServ + name. To request a cloak, send an email to + &a.irc.email; with your requested hostmask and NickServ + account name. + - svn+ssh://repo.FreeBSD.org/ports - (see also ). - + + Gandi.net Discounts - - 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 - /local/mail/repository-name-developers-archive - and - /local/mail/repository-name-committers-archive - on the FreeBSD.org - cluster.) - + Gandi provides website hosting, cloud computing, domain + registration, and X.509 certificate services. + Gandi offers an E-rate discount to all &os; developers. + Send mail to non-profit@gandi.net using your + @freebsd.org mail address, and indicate + your Gandi handle. + + - - Core Team monthly - reports - /home/core/public/monthly-reports - on the FreeBSD.org - cluster. - + + Commit Bit Types - - Ports Management Team monthly - reports - /home/portmgr/public/monthly-reports - on the FreeBSD.org - cluster. - + The &os; 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 &os; 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. - - Noteworthy src/ SVN - Branches - - stable/8 (8.X-STABLE), - stable/9 (9.X-STABLE), - stable/10 (10.X-STABLE), - head (-CURRENT) - - + + + + + Committer Type + Responsible + Tree Components + + + + src + core@ + src/, doc/ subject to appropriate review + + + + doc + doceng@ + doc/, ports/, src/ documentation + + + + ports + portmgr@ + ports/ + + - &man.ssh.1; is required to connect to the project hosts. - For more information, see . + 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. - Useful links: + 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. - - - &os; - Project Internal Pages - + + Policy for Committer Activity in Other Trees - - &os; - Project Hosts - + + + All committers may modify + base/head/share/misc/committers-*.dot, + base/head/usr.bin/calendar/calendars/calendar.freebsd, + and + ports/head/astro/xearth/files. + + + + doc committers may commit + documentation changes to 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. + + + + Any committer may make changes to any other tree + with an "Approved by" from a non-mentored committer with + the appropriate bit. + + + + Committers can aquire 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. + + + + "Approved by" is only acceptable from non-mentored src + committers -- mentored committers can provide a "Reviewed + by" but not an "Approved by". + + + + - - &os; - Project Administrative Groups - - + + New Project Participant Setup, Conventions, and + Traditions + + There are a number of things to do as a new developer. + The first set of steps is specific to committers only. These + steps must be done by a mentor for those who are not + committers. + + + Mentors + + All new developers have a mentor assigned to them for + the first few months. A mentor is responsible for teaching + the mentee the rules and conventions of the project and + guiding their first steps in the developer community. The + mentor is also personally responsible for the mentee's actions + during this initial period. + + For committers: do not commit anything without first + getting mentor approval. Document that approval with an + Approved by: line in the commit + message. + + When the mentor decides that a mentee has learned the + ropes and is ready to commit on their own, the mentor + announces it with a commit to + conf/mentors. This file is in the + svnadmin branch of each + repository: + + + + + + src + base/svnadmin/conf/mentors + + + + doc + doc/svnadmin/conf/mentors + + + + ports + ports/svnadmin/conf/mentors + + + + + + + + Development Environment + + &os; contributors are encouraged to contribute to the project + using a &os; development environment. &os; is a self-hosted + operating system with a wide array of available graphical desktops + and contributing to &os; using &os; is the + most efficient way of identifying and resolving any issues you may + encounter. The myriad of available virtualization options make + this easier than ever if a bare-metal &os; system is not available + to you. See the Installing &os; + section of the FreeBSD Handbook for information on installing &os; + + + + + Setup Procedures for New Committers and Contributors + + The fictional user "J. Random User <jru@freebsd.org>" + will be used in these instructions. Replace jru's information + with your name and usrename as appropriate. + + Those who have been given commit rights to the &os; + repositories must follow these steps. + + + + Get mentor approval before committing each of these + changes! + + + + The .ent and + .xml files mentioned below exist in + the &os; Documentation Project SVN repository at svn.freebsd.org/doc/. + + + + New files that do not have the + FreeBSD=%H + svn:keywords property will be rejected + when attempting to commit them to the repository. Be sure + to read + + regarding adding and removing files. Verify that + ~/.subversion/config contains the + necessary auto-props entries from + auto-props.txt mentioned + there. + + + + All src commits should go to + &os.current; first before being merged to &os.stable;. + The &os.stable; branch must maintain + ABI and API + compatibility with earlier versions of that branch. Do + not merge changes that break this compatibility. + + + + + Steps for New Committers and Contributors + + + Add an Author !ENTITY Entry + + Committers: Add an author !ENTITY entry to + doc/head/share/xml/authors.ent. + This is an XML element that is used throughout the &os; + build system. Later steps depend on this entity, and + missing this step will cause the doc/ + build to fail. This is a relatively easy task, but remains + a good first test of version control skills. Entries are + sorted by @freebsd.org username. + + +... +<!ENTITY a.dexter "J. Random User"> +<!ENTITY a.jru.email "&a.jru; <email xmlns='http://docbook.org/ns/docbook'>jru@FreeBSD.org</email>"> +... + + + + + + Update the List of Developers or Contributors + + + Committers: Add an entry to the Developers section + of +doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml + to appear on the Contributors + List. Entries are sorted by last name. + + +... + <listitem> + <para>&a.jru.email;</para> + </listitem> +... + + + Contributors becoming Committers: Transfer your !ENTITY + entry from the Additional Contributors to the + Developers section. + + + + Add a News Item + + Add a News Item entry to + doc/head/share/xml/news.xml + Look for the other entries that announce new committers and + follow the format. Use the date from the commit bit approval + email from core@freebsd.org. + + +... + <month> + <name>9</name> + + <day> + <name>23</name> + + <event> + <p>New committer: + <a href="mailto:jru@FreeBSD.org">J. Random User</a> + (doc)</p> + </event> + </day> + </month> +... + + + + + Add a <acronym>PGP</acronym>/<acronym>GnuPG</acronym> Key + + If you do not have a + PGP/GnuPG key or your key + is expiring relatively soon, refer to + for instructions on how to + create a new PGP/GnuPG + key. + + Add your PGP/GnuPG + key to + doc/head/share/pgpkeys/pgpkeys.ent + and + doc/head/share/pgpkeys/pgpkeys-developers.xml + using the + doc/head/share/pgpkeys/addkey.sh shell + script. See README + file for full details. Note the instructions provided by + the script. + + &prompt.user; ./addkey.sh jru +WARNING: Multiple keys found for <jru@FreeBSD.org<; exporting all. +WARNING: If this is not what you want, specify a key ID on the command line. +Generating jru.key... +Adding key to entity list... + +Unless you are already listed there, you should now add the following +text to pgpkeys-developers.xml. Remember to keep the list sorted by +last name! + + <sect2 xmlns="http://docbook.org/ns/docbook" xml:id="pgpkey-jru"> + <title>&a.jru.email;</title> + &pgpkey.jru; + </sect2> + +If this is a role key or you are a core member, you should add it to +either pgpkeys-officers.xml or pgpkeys-core.xml instead. + +If this is a new entry, don't forget to run the following commands +before committing: + +% svn add jru.key +% svn propset svn:keywords FreeBSD=%H jru.key + + + Use + doc/head/share/pgpkeys/checkkey.sh to + verify that keys meet minimal best-practices + standards. + + &prompt.user; ./checkkey.sh jru +WARNING: Multiple keys found for <jru@FreeBSD.org>; checking all. +WARNING: If this is not what you want, specify a key ID on the command line. +key E9A628D03AC59BFB: RSA, 2048 bits + key okay, E9A628D03AC59BFB meets minimal requirements + + + After adding and checking a key, add both updated + files to source control and then commit them. Entries in + this file are sorted by last name. + + + It is very important to have a current + PGP/GnuPG key in + the repository. The key may be required for positive + identification of a committer. For example, the + &a.admins; might need it for account recovery. A + complete keyring of freebsd.org users is + available for download from http://www.freebsd.org/doc/pgpkeyring.txt. + + + + + Update Mentor and Mentee Information + + Add an entry to the current committers section of + base/head/share/misc/committers-repository.dot + where repository is + doc, ports, or + src, depending on the commit privileges + granted. + + Add an entry for each additional mentor/mentee + relationship in the bottom section. + + + + Generate a <application>Kerberos</application> + Password + + See to generate or + set a Kerberos for use with + other &os; services like the bug tracking database. + + + + Set Up a Phabricator Account + + A reviews.freebsd.org + a.k.a. "Phabricator" account allows you to submit patches for + review by other project members for discussion and revision prior + to committing. Visit reviews.freebsd.org/auth/register/ + to set up a Phabricator account. If you already have a Phabricator + account with non-&os; email address, log into Phabricator and add + your @freebsd.org email address to your profile. This will require + you to verify your address, after which you can make your + @freebsd.org address your primary address. Mailphabric-admin@freebsd.org + and ask that your username be changed to your @freebsd.org address. + Note that when your account type is changed, you will no longer be + able to log in with your non-&os; password but rather will need to + use Keberos. See + for details. + + + + Optional: Create a Wiki Account + + A wiki.freebsd.org + account allows you to share projects and ideas that are not + suitable for the primary &os; documentation. wiki.freebsd.org + is also used for event organization such as DevSummits. Visit + wiki.freebsd.org/action/newaccount/FrontPage?action=newaccount + to create a new Wiki account. + + + + Optional: Update Wiki Information + + Some project members add entries to + How + We Got Here, + Irc + Nicks, and Dogs + of FreeBSD pages. + + + + Optional: Add Additional Personal Information + + Some project members add entries for themselves to + ports/astro/xearth/files/freebsd.committers.markers + and + src/usr.bin/calendar/calendars/calendar.freebsd + to show where they are located or the date of their + birthday. + + + + Optional: Prevent Duplicate Mailings + + Subscribers to &a.svn-src-all.name;, + &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish + to unsubscribe to avoid receiving duplicate copies of + commit messages and followups. + + + + + + For Everyone + + + + Introduce yourself to the other developers, otherwise + no one will have any idea who you are or what you are + working on. The introduction need not be a comprehensive + biography, just write a paragraph or two about who you + are, what you plan to be working on as a developer in + &os;, and who will be your mentor. Email this to the + &a.developers; and you will be on your way! + + + + Log into freefall.freebsd.org + and create a + /var/forward/user + (where user is your username) + file containing the e-mail address where you want mail + addressed to + yourusername@freebsd.org to be + forwarded. This includes all of the commit messages as + well as any other mail addressed to the &a.committers; and + the &a.developers;. Really large mailboxes which have + taken up permanent residence on + freefall may get truncated + without warning if space needs to be freed, so forward it + or read it and you will not lose it. + + Due to the severe load dealing with SPAM places on the + central mail servers that do the mailing list processing + the front-end server does do some basic checks and will + drop some messages based on these checks. At the moment + proper DNS information for the connecting host is the only + check in place but that may change. Some people blame + these checks for bouncing valid email. If you want these + checks turned off for your email you can place a file + named .spam_lover in your home + directory on freefall.freebsd.org + to disable the checks for your email. + + + + + Those who are developers but not committers will + not be subscribed to the committers or developers mailing + lists. The subscriptions are derived from the access + rights. + + + + + + Open<acronym>SSH</acronym> Keys for &os; + + Cryptographic keys conforming to the + OpenSSH (Secure + Shell) standard are used by the &os; project to allow + access by committers to various &os; servers for source + commits, communication and project management. + + + Creating an OpenSSH Key + + Existing OpenSSH keys can be used, but only if they + comply with the ECDSA, + Ed25519 or RSA standards. + + + For those who do not yet have an + OpenSSH key, or need a new key to meet + &os; security requirements. + + + + Generate a key pair using &man.ssh-keygen.1;. The key + pair will be saved to your $HOME/.ssh/ + directory. + + + Only ECDSA, + Ed25519 or RSA keys + are supported. + + + + + &prompt.user; ssh-keygen +Enter file in which to save the key (/home/jru/.ssh/id_rsa): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /home/jru/.ssh/id_rsa. +Your public key has been saved in /home/jru/.ssh/id_rsa.pub. +The key fingerprint is: +SHA256:E+w9UzR94MPczAeqt/IJbXYmj2/+L4wr38NofwhmDts jru@host +The key's randomart image is: ++---[RSA 2048]----+ +| +o.o.| +| . =.*.oo| +| o O.* o| +| . o * + + | +| S + o = +| +| ..o+* = | +| B *o..| +| o E.* o| +| +o.o++| ++----[SHA256]-----+ + + + + + Send your public key + ($HOME/.ssh/id_ecdsa.pub, + $HOME/.ssh/id_ed25519.pub, or + $HOME/.ssh/id_rsa.pub) + to the person setting you up as a committer so it can be put + into + yourlogin + in + /etc/ssh-keys/ on + freefall. + + + + If you do not wish to type your password in every time + you use &man.ssh.1;, and you use keys to + authenticate, &man.ssh-agent.1; is there for your + convenience. If you want to use &man.ssh-agent.1;, make + sure that you run it before running other applications. X + users, for example, usually do this from their + .xsession or + .xinitrc. See &man.ssh-agent.1; for + details. + + + + + + OpenSSH Server-Side User Account Key Management + + The &os; Cluster provides a self-serve service for public + OpenSSH key management at + keymaster.freebsd.org. This service + allows you to list, add and remove OpenSSH keys associated + with your @freebsd.org username. + + &prompt.user; ssh keymaster.freebsd.org +============================================================================ + READ ME CAREFULLY +============================================================================ +MAKE SURE you know how to use PGP and that your key in the handbook is +current. PGP signed email to accounts@ is your primary recovery option. + +You may use the following commands: +LIST: -- show your current keys + ssh jru@keymaster.freebsd.org list + +ADD: -- Add a SINGLE public key FROM SSH STANDARD INPUT + ssh jru@keymaster.freebsd.org add < ~/.ssh/id_ed25519.pub + Alternative: "ssh jru@keymaster.freebsd.org add" and cut/paste. +(Must pass basic santiy checks. ED25519, RSA>=2048, ECDSA allowed) + +REMOVE: -- interactively select keys to remove from the list. + ssh jru@keymaster.freebsd.org remove + +You will receive an email copy of any changes with cc: to admin folks. +If you need help for non-standard key configurations: accounts@freebsd.org + +Any changes that you make will take approximately 10 minutes to go live. +============================================================================ + + + + + Local OpenSSH Key Management + + Now you should be able to use &man.ssh-add.1; for + authentication once per session. This will prompt you for + your private key's pass phrase, and then store it in your + authentication agent (&man.ssh-agent.1;). If you no longer + wish to have your key stored in the agent, issuing + ssh-add -d will remove it. + + Test by doing something such as ssh + freefall.freebsd.org ls /usr. + + For more information, see + security/openssh, + &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, + &man.ssh-keygen.1;, and &man.scp.1;. + + For information on adding, changing, or removing + &man.ssh.1; keys, see this + article. + - Open<acronym>PGP</acronym> Keys for &os; + <acronym>PGP</acronym>/<acronym>GnuPG</acronym> Keys for + &os; Cryptographic keys conforming to the - OpenPGP (Pretty Good - Privacy) standard are used by the &os; 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 + PGP (Pretty Good + Privacy)/GnuPG standard are used + by the &os; project to authenticate committers. Messages + carrying important information like new public + PGP/GnuPG can be signed + with the PGP/GnuPG key to + prove that they are really from the committer. See PGP & - GPG: Email for the Practical Paranoid by Michael Lucas + GPG: Email for the Practical Paranoid by Michael Lucas and for more information. - Creating a Key + Creating a <acronym>PGP</acronym>/<acronym>GnuPG</acronym> + Key - Existing keys can be used, but should be checked with - doc/head/share/pgpkeys/checkkey.sh - first. + Existing PGP/GnuPG + keys can be used, but should be checked with doc/head/share/pgpkeys/checkkey.sh + first. For those who do not yet have an - OpenPGP key, or need a new key to meet &os; - security requirements, here we show how to generate - one. + PGP/GnuPG key, or need a + new key to meet &os; security requirements, here we show how + to generate one. - Install - security/gnupg. Enter - these lines in ~/.gnupg/gpg.conf to - set minimum acceptable defaults: + Install security/gnupg. Enter these + lines in ~/.gnupg/gpg.conf to set + minimum acceptable defaults: fixed-list-mode keyid-format 0xlong @@ -239,6 +833,9 @@ Generate a key: + Note that you must have full control of the terminal + for GPG key generation to succeed. Using 'su' will fail. + &prompt.user; gpg --full-gen-key gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -261,16 +858,16 @@ <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) 3y -Key expires at Wed Nov 4 17:20:20 2015 MST +Key expires at Wed Nov 4 17:20:20 2020 MST Is this correct? (y/N) y GnuPG needs to construct a user ID to identify your key. -Real name: Chucky Daemon -Email address: notreal@example.com +Real name: J. Random User +Email address: jru@freebsd.org Comment: You selected this USER-ID: - "Chucky Daemon <notreal@example.com>" + "J. Random User <jru@freebsd.org>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o You need a Passphrase to protect your secret key. @@ -315,7 +912,7 @@ Protect your private key and passphrase. If either the private key or passphrase may have been compromised or disclosed, immediately notify - accounts@FreeBSD.org and revoke the key. + accounts@freebsd.org and revoke the key. Committing the new key is shown in . @@ -334,11 +931,11 @@ Bugzilla + xlink:href="http://bugs.freebsd.org/bugzilla">Bugzilla Jenkins + xlink:href="http://jenkins.freebsd.org">Jenkins @@ -346,7 +943,29 @@ reset a Kerberos password for an existing account using a random password generator: - &prompt.user; ssh kpasswd.freebsd.org + &prompt.user; ssh jru@kpasswd.freebsd.org +FreeBSD 12.0-CURRENT (CLUSTER) #0 r306376: Tue Sep 27 19:02:08 UTC 2016 + +Unauthorized access is strictly prohibited. +role=kpasswd build=amd64_12@306376 + +Hi there, jru.. + +Sanity checking.. +Creating initial instance for jru +=================================================================== +Generating a strong, evil random password.. +=================================================================== +Your new, ready to forget, password: Fop%o3wee3ei +=================================================================== +You can change it with kpasswd(1) on any machine in the cluster, +but please consider using a password manager instead. Things like +LastPass, 1Password etc work great. + +Run this again to get a different random password. + +Connection to kpasswd.freebsd.org closed. + This must be done from a machine outside of the &os;.org @@ -355,11 +974,19 @@ A Kerberos password can also be set manually by logging into freefall.FreeBSD.org and + class="fqdomainname">freefall.freebsd.org and running: - &prompt.user; kpasswd - + &prompt.user; ssh jru@freefall.freebsd.org +&prompt.user; kpasswd +jru@FREEBSD.ORG's Password: +kpasswd: krb5_get_init_creds: Preauthentication failed +jru@freefall:~ % kpasswd +jru@FREEBSD.ORG's Password: +New password: +Verifying - New password: +Success : Password changed + Unless you have used the Kerberos-authenticated services of the &os;.org cluster previously, @@ -371,3673 +998,3347 @@ - - Commit Bit Types + + Administrative Links - The &os; 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 &os; 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. + + + + + + + Login Methods + &man.ssh.1;, protocol 2 only + + + + Main Shell Host + freefall.freebsd.org + + + + src/ Subversion + Root + svn+ssh://repo.freebsd.org/base + (see also ). + + + + doc/ Subversion + Root + svn+ssh://repo.freebsd.org/doc + (see also ). + + + + ports/ Subversion + Root + + svn+ssh://repo.freebsd.org/ports + (see also ). + + + + 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 + /local/mail/repository-name-developers-archive + and + /local/mail/repository-name-committers-archive + on the freebsd.org + cluster.) + + + + Core Team monthly + reports + /home/core/public/monthly-reports + on the freebsd.org + cluster. + + + + Ports Management Team monthly + reports + /home/portmgr/public/monthly-reports + on the freebsd.org + cluster. + + + + Noteworthy src/ SVN + Branches + + stable/10 (10.X-STABLE), + stable/11 (11.X-STABLE), + head (12-CURRENT) + + + + - - - - - Committer Type - Responsible - Tree Components - + &man.ssh.1; is required to connect to the project hosts. + For more information, see . - - src - core@ - src/, doc/ subject to appropriate review - + Useful links: - - doc - doceng@ - doc/, ports/, src/ documentation - + + + &os; + Project Internal Pages + - - ports - portmgr@ - ports/ - - - - + + &os; + Project Hosts + - 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. + + - 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. + + FreeBSD Teams - - Policy for Committer Activity in Other Trees + The &os; project is organized into several teams that + share responsibility for various aspects of the project. + See &os; + Project Administrative Groups for a complete + list of the active &os; teams. - - - All committers may modify - base/head/share/misc/committers-*.dot, - base/head/usr.bin/calendar/calendars/calendar.freebsd, - and - ports/head/astro/xearth/files. - + + + &a.doceng; - - doc committers may commit - documentation changes to 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. - + + doceng is the group responsible for the documentation + build infrastructure, approving new documentation + committers, and ensuring that the &os; website and + documentation on the FTP site is up to date with respect + to the subversion tree. It is + not a conflict resolution body. + The vast majority of documentation related discussion + takes place on the &a.doc;. More details regarding the + doceng team can be found in its charter. + Committers interested in contributing to the documentation + should familiarize themselves with the Documentation + Project Primer. + + - - Any committer may make changes to any other tree - with an "Approved by" from a non-mentored committer with - the appropriate bit. - + - - "Approved by" is only acceptable from non-mentored src - committers -- mentored committers can provide a "Reviewed - by" but not an "Approved by". - - - - + + &a.portmgr; - - Subversion Primer + + portmgr is the group responsible for maintenance + of the &os; Ports Collection, a repository of third + party software that is ported to &os;. Committers + interested in contributing to &os; Ports should + familiarize themselves with the Porter's + Handbook. + + - It is assumed that you are already familiar with the basic - operation of Subversion. If not, start by reading the - Subversion - Book. - - - Introduction - - The &os; source repository switched from - CVS to Subversion on May 31st, 2008. The - first real SVN commit is - r179447. + + &a.re; - The &os; doc/www repository switched - from CVS to Subversion on May 19th, 2012. - The first real SVN commit is - r38821. + + The &a.re; team is responsible for setting &os; + release deadlines and controlling the release process. + During code freezes, the release engineers have final + authority on all changes to the system for whichever + branch is pending release status. If there is something + you want merged from &os.current; to &os.stable; + (whatever values those may have at any given time), + these are the people to talk to about it. + + + - The &os; ports repository switched - from CVS to Subversion on July 14th, 2012. - The first real SVN commit is - r300894. + + &a.security-officer; - Subversion can be installed from the &os; Ports - Collection by issuing these commands: + + The &a.security-officer; is responsible for overseeing + all security-related issues of the &os; project. + + - &prompt.root; pkg install subversion + + Cluster Admin - + + The Cluster Admin team is responsible for overseeing + the &os; project infrastructure. + + + + + - There are a few ways to obtain a working copy of the tree - from Subversion. This section will explain them. + + FreeBSD Mailing Lists - - Direct Checkout + The &os; maintains several mailing lists to facilitate + communication within the project. - The first is to check out directly from the main - repository. For the src tree, - use: + + + &a.committers; - &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + &a.svn-src-all.name;, &a.svn-ports-all.name; and + &a.svn-doc-all.name; are the mailing lists that the + version control system uses to send commit messages to. + You should never send email directly + to these lists. You should only send replies to this list + when they are short and are directly related to a + commit. + + - For the doc tree, use: + + &a.developers; - &prompt.user; svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc + + All committers are subscribed to -developers. This + list was created to be a forum for the committers + community issues. Examples are Core + voting, announcements, etc. + + The &a.developers; is for the exclusive use of &os; + committers. In order to develop &os;, committers must + have the ability to openly discuss matters that will be + resolved before they are publicly announced. Frank + discussions of work in progress are not suitable for open + publication and may harm &os;. + + All &os; committers are expected not to + not publish or forward messages from the + &a.developers; outside the list membership without + permission of all of the authors. Violators will be + removed from the + &a.developers;, resulting in a suspension of commit + privileges. Repeated or flagrant violations may result in + permanent revocation of commit privileges. + + This list is not intended as a + place for code reviews or for any technical discussion. + In fact using it as such hurts the &os; Project as it + gives a sense of a closed list where general decisions + affecting all of the &os; using community are made without + being open. Last, but not least + never, never ever, email the &a.developers; and + CC:/BCC: another &os; list. Never, ever email + another &os; email list and CC:/BCC: the &a.developers;. + Doing so can greatly diminish the benefits of this + list. + + + + - For the ports tree, use: + + &os; Community Rules - &prompt.user; svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports + As members of the &os; project, you form the public face of + the project, and how you behave has a vital impact on the public + perception of it. - - Though the remaining examples in this document are - written with the workflow of working with the - src tree in mind, the underlying - concepts are the same for working with the - doc and the ports - tree. - Ports related Subversion operations are listed in - . - + &os; Code of Conduct - The above command will check out a - CURRENT source tree as - /usr/src/, - which can be any target directory on the local filesystem. - Omitting the final argument of that command causes the - working copy, in this case, to be named head, - but that can be renamed safely. - - svn+ssh means the - SVN protocol tunnelled over - SSH. The name of the server is - repo.freebsd.org, base - is the path to the repository, and head - is the subdirectory within the repository. - - If your &os; login name is different from your login - name on your local machine, you must either include it in - the URL (for example - svn+ssh://jarjar@repo.freebsd.org/base/head), - or add an entry to your ~/.ssh/config - in the form: + The &os; + Code + of Conduct exists to provide a consistent policy on + unacceptable behavior by &os; community members. - Host repo.freebsd.org - User jarjar + The following expands on the parts of the Code of + Conduct specific to committers. - This is the simplest method, but it is hard to tell just - yet how much load it will place on the repository. + + + Respect other committers. + - - The svn diff does not require - access to the server as SVN stores a - reference copy of every file in the working copy. This, - however, means that Subversion working copies are very - large in size. - - + + Respect other contributors. + - - Checkout from a Mirror + + Discuss any significant change + before committing. + - Check out a working copy from a mirror by - substituting the mirror's URL for - svn+ssh://repo.freebsd.org/base. This - can be an official mirror or a mirror maintained by using - svnsync. + + Respect existing maintainers (if listed in the + MAINTAINER field in + Makefile or in + MAINTAINER in the top-level + directory). + - There is a serious disadvantage to this method: every - time something is to be committed, a - svn relocate to the master repository has - to be done, remembering to svn relocate - back to the mirror after the commit. Also, since - svn relocate only works between - repositories that have the same UUID, some hacking of the - local repository's UUID has to occur before it is possible - to start using it. + + Any disputed change must be backed out pending + resolution of the dispute if requested by a maintainer. + Security related changes may override a maintainer's wishes + at the Security Officer's discretion. + - The hassle of a local - svnsync mirror probably is not worth it - unless the network connectivity situation or other factors - demand it. If it is needed, see the end of this chapter for - information on how to set one up. - + + Changes go to &os.current; before &os.stable; unless + specifically permitted by the release engineer or unless + they are not applicable to &os.current;. Any non-trivial or + non-urgent change which is applicable should also be allowed + to sit in &os.current; for at least 3 days before merging so + that it can be given sufficient testing. The release + engineer has the same authority over the &os.stable; branch + as outlined for the maintainer in rule #5. + - - <literal>RELENG_*</literal> Branches and General - Layout + + Do not fight in public with other committers; it looks + bad. + - In svn+ssh://repo.freebsd.org/base, - base refers to the source tree. - Similarly, ports refers to the ports - tree, and so on. These are separate repositories with their - own change number sequences, access controls and commit - mail. + + Respect all code freezes and read the + committers and + developers mailing lists in a timely + manner so you know when a code freeze is in effect. + - For the base repository, HEAD refers to the -CURRENT - tree. For example, head/bin/ls is what - would go into /usr/src/bin/ls in a - release. Some key locations are: + + When in doubt on any procedure, ask first! + - - - /head/ which corresponds to - HEAD, also known as - -CURRENT. - + + Test your changes before committing them. + - - /stable/n - which corresponds to - RELENG_n. - + + Do not commit to anything under the + src/contrib, + src/crypto, or + src/sys/contrib trees without + explicit approval from the respective + maintainer(s). + + - - /releng/n.n - which corresponds to - RELENG_n_n. - + As noted, breaking some of these rules can be grounds for + suspension or, upon repeated offense, permanent removal of + commit privileges. Individual members of core have the power to + temporarily suspend commit privileges until core as a whole has + the chance to review the issue. In case of an + emergency (a committer doing damage to the + repository), a temporary suspension may also be done by the + repository meisters. Only a 2/3 majority of core has the + authority to suspend commit privileges for longer than a week or + to remove them permanently. This rule does not exist to set + core up as a bunch of cruel dictators who can dispose of + committers as casually as empty soda cans, but to give the + project a kind of safety fuse. If someone is out of control, it + is important to be able to deal with this immediately rather + than be paralyzed by debate. In all cases, a committer whose + privileges are suspended or revoked is entitled to a + hearing by core, the total duration of the + suspension being determined at that time. A committer whose + privileges are suspended may also request a review of the + decision after 30 days and every 30 days thereafter (unless the + total suspension period is less than 30 days). A committer + whose privileges have been revoked entirely may request a review + after a period of 6 months has elapsed. This review policy is + strictly informal and, in all cases, core + reserves the right to either act on or disregard requests for + review if they feel their original decision to be the right + one. - - /release/n.n.n - which corresponds to - RELENG_n_n_n_RELEASE. - + In all other aspects of project operation, core is a subset + of committers and is bound by the + same rules. Just because someone is in + core this does not mean that they have special dispensation to + step outside any of the lines painted here; core's + special powers only kick in when it acts as a + group, not on an individual basis. As individuals, the core + team members are all committers first and core second. - - /vendor* is the vendor branch - import work area. This directory itself does not - contain branches, however its subdirectories do. This - contrasts with the stable, - releng and - release directories. - + + Details - - /projects and - /user feature a branch work area, - like in Perforce. As above, the - /user directory does not contain - branches itself. - - - + + + Respect other committers. - - &os; Documentation Project Branches and - Layout + This means that you need to treat other committers as + the peer-group developers that they are. Despite our + occasional attempts to prove the contrary, one does not + get to be a committer by being stupid and nothing rankles + more than being treated that way by one of your peers. + Whether we always feel respect for one another or not (and + everyone has off days), we still have to + treat other committers with respect + at all times, on public forums and in private + email. + + Being able to work together long term is this + project's greatest asset, one far more important than any + set of changes to the code, and turning arguments about + code into issues that affect our long-term ability to work + harmoniously together is just not worth the trade-off by + any conceivable stretch of the imagination. + + To comply with this rule, do not send email when you + are angry or otherwise behave in a manner which is likely + to strike others as needlessly confrontational. First + calm down, then think about how to communicate in the most + effective fashion for convincing the other person(s) that + your side of the argument is correct, do not just blow off + some steam so you can feel better in the short term at the + cost of a long-term flame war. Not only is this very bad + energy economics, but repeated displays of + public aggression which impair our ability to work well + together will be dealt with severely by the project + leadership and may result in suspension or termination of + your commit privileges. The project leadership will take + into account both public and private communications + brought before it. It will not seek the disclosure of + private communications, but it will take it into account + if it is volunteered by the committers involved in the + complaint. + + All of this is never an option which the project's + leadership enjoys in the slightest, but unity comes first. + No amount of code or good advice is worth trading that + away. + + + + Respect other contributors. + + You were not always a committer. At one time you were + a contributor. Remember that at all times. Remember what + it was like trying to get help and attention. Do not + forget that your work as a contributor was very important + to you. Remember what it was like. Do not discourage, + belittle, or demean contributors. Treat them with + respect. They are our committers in waiting. They are + every bit as important to the project as committers. + Their contributions are as valid and as important as your + own. After all, you made many contributions before you + became a committer. Always remember that. + + Consider the points raised under + and apply them also to + contributors. + + + + Discuss any significant change + before committing. + + The repository is not where changes should be + initially submitted for correctness or argued over, that + should happen first in the mailing lists or by use of the + Phabricator service and the commit should only happen once + something resembling consensus has been reached. This + does not mean that you have to ask permission before + correcting every obvious syntax error or manual page + misspelling, simply that you should try to develop a feel + for when a proposed change is not quite such a no-brainer + and requires some feedback first. People really do not + mind sweeping changes if the result is something clearly + better than what they had before, they just do not like + being surprised by those changes. + The very best way of making sure that you are on the right + track is to have your code reviewed by one or more other + committers. + + When in doubt, ask for review! + + + + Respect existing maintainers if listed. + + Many parts of &os; are not owned in + the sense that any specific individual will jump up and + yell if you commit a change to their area, + but it still pays to check first. One convention we use + is to put a maintainer line in the + Makefile for any package or subtree + which is being actively maintained by one or more people; + see http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html + for documentation on this. Where sections of code have + several maintainers, commits to affected areas by one + maintainer need to be reviewed by at least one other + maintainer. In cases where the + maintainer-ship of something is not clear, + you can also look at the repository logs for the file(s) + in question and see if someone has been working recently + or predominantly in that area. + + Other areas of &os; fall under the control of someone + who manages an overall category of &os; evolution, such as + internationalization or networking. See http://www.freebsd.org/administration.html + for more information on this. + + + + Any disputed change must be backed out pending + resolution of the dispute if requested by a maintainer. + Security related changes may override a maintainer's + wishes at the Security Officer's discretion. + + This may be hard to swallow in times of conflict (when + each side is convinced that they are in the right, of + course) but a version control system makes it unnecessary + to have an ongoing dispute raging when it is far easier to + simply reverse the disputed change, get everyone calmed + down again and then try to figure out what is the best way + to proceed. If the change turns out to be the best thing + after all, it can be easily brought back. If it turns out + not to be, then the users did not have to live with the + bogus change in the tree while everyone was busily + debating its merits. People very + rarely call for back-outs in the repository since + discussion generally exposes bad or controversial changes + before the commit even happens, but on such rare occasions + the back-out should be done without argument so that we + can get immediately on to the topic of figuring out + whether it was bogus or not. + + + + Changes go to &os.current; before &os.stable; unless + specifically permitted by the release engineer or unless + they are not applicable to &os.current;. Any non-trivial + or non-urgent change which is applicable should also be + allowed to sit in &os.current; for at least 3 days before + merging so that it can be given sufficient testing. The + release engineer has the same authority over the + &os.stable; branch as outlined in rule #5. + + This is another do not argue about it + issue since it is the release engineer who is ultimately + responsible (and gets beaten up) if a change turns out to + be bad. Please respect this and give the release engineer + your full cooperation when it comes to the &os.stable; + branch. The management of &os.stable; may frequently seem + to be overly conservative to the casual observer, but also + bear in mind the fact that conservatism is supposed to be + the hallmark of &os.stable; and different rules apply + there than in &os.current;. There is also really no point + in having &os.current; be a testing ground if changes are + merged over to &os.stable; immediately. Changes need a + chance to be tested by the &os.current; developers, so + allow some time to elapse before merging unless the + &os.stable; fix is critical, time sensitive or so obvious + as to make further testing unnecessary (spelling fixes to + manual pages, obvious bug/typo fixes, etc.) In other + words, apply common sense. + + Changes to the security branches (for example, + releng/9.3) must be approved by a + member of the &a.security-officer;, or in some cases, by a + member of the &a.re;. + + + + Do not fight in public with other committers; it looks + bad. + + This project has a public image to uphold and that + image is very important to all of us, especially if we are + to continue to attract new members. There will be + occasions when, despite everyone's very best attempts at + self-control, tempers are lost and angry words are + exchanged. The best thing that can be done in such cases + is to minimize the effects of this until everyone has + cooled back down. That means that you should not air your + angry words in public and you should not forward private + correspondence or other private communications to public + mailing lists, mail aliases, instant messaging channels or + social media sites. What people say one-to-one is often + much less sugar-coated than what they would say in public, + and such communications therefore have no place there - + they only serve to inflame an already bad situation. If + the person sending you a flame-o-gram at least had the + grace to send it privately, then have the grace to keep it + private yourself. If you feel you are being unfairly + treated by another developer, and it is causing you + anguish, bring the matter up with core rather than taking + it public. Core will do its best to play peace makers and + get things back to sanity. In cases where the dispute + involves a change to the codebase and the participants do + not appear to be reaching an amicable agreement, core may + appoint a mutually-agreeable third party to resolve the + dispute. All parties involved must then agree to be bound + by the decision reached by this third party. + + + + Respect all code freezes and read the + committers and + developers mailing list on a timely + basis so you know when a code freeze is in effect. + + Committing unapproved changes during a code freeze is + a really big mistake and committers are expected to keep + up-to-date on what is going on before jumping in after a + long absence and committing 10 megabytes worth of + accumulated stuff. People who abuse this on a regular + basis will have their commit privileges suspended until + they get back from the &os; Happy Reeducation Camp we + run in Greenland. + + + + When in doubt on any procedure, ask first! + + Many mistakes are made because someone is in a hurry + and just assumes they know the right way of doing + something. If you have not done it before, chances are + good that you do not actually know the way we do things + and really need to ask first or you are going to + completely embarrass yourself in public. 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 refer to the + &os; + Internal Page for a list of available resources. + As other architectures are added to the &os; supported + platforms list, the appropriate shared testing resources + will be made available. + + + + Do not commit to anything under the + src/contrib, + src/crypto, and + src/sys/contrib trees without + explicit approval from the respective + maintainer(s). + + The trees mentioned above are for contributed software + usually imported onto a vendor branch. Committing + something there, even if it does not take the file off the + vendor branch, may cause unnecessary headaches for those + responsible for maintaining that particular piece of + software. Thus, unless you have + explicit approval from the maintainer + (or you are the maintainer), do not + commit there! + + Please note that this does not mean you should not try + to improve the software in question; you are still more + than welcome to do so. Ideally, you should submit your + patches to the vendor. If your changes are + &os;-specific, talk to the maintainer; they may be + willing to apply them locally. But whatever you do, do + not commit there by yourself! + + Contact the &a.core; if you wish to take up + maintainership of an unmaintained part of the tree. + + + - In svn+ssh://repo.freebsd.org/doc, - doc refers to the repository root of - the source tree. + + Other Suggestions - In general, most &os; Documentation Project work will be - done within the head/ branch of the - documentation source tree. + When committing documentation changes, use a spell checker + before committing. For all XML docs, verify that the + formatting directives are correct by running + make lint and + textproc/igor. - &os; documentation is written and/or translated to - various languages, each in a separate - directory in the head/ - branch. + For manual pages, run sysutils/manck + and textproc/igor + over the manual page to verify all of the cross + references and file references are correct and that the man + page has all of the appropriate MLINKs + installed. - Each translation set contains several subdirectories for - the various parts of the &os; Documentation Project. A few - noteworthy directories are: + Do not mix style fixes with new functionality. A style + fix is any change which does not modify the functionality of + the code. Mixing the changes obfuscates the functionality + change when asking for differences between revisions, which + can hide any new bugs. Do not include whitespace changes with + content changes in commits to doc/ . + The extra clutter in the diffs + makes the translators' job much more difficult. Instead, make + any style or whitespace changes in separate commits that are + clearly labeled as such in the commit message. + - - - /articles/ contains the source - code for articles written by various &os; - contributors. - + + Deprecating Features - - /books/ contains the source - code for the different books, such as the - &os; Handbook. - + When it is necessary to remove functionality from software + in the base system the following guidelines should be followed + whenever possible: - - /htdocs/ contains the source - code for the &os; website. - - - + + + Mention is made in the manual page and possibly the + release notes that the option, utility, or interface is + deprecated. Use of the deprecated feature generates a + warning. + + + + The option, utility, or interface is preserved until + the next major (point zero) release. + + + + The option, utility, or interface is removed and no + longer documented. It is now obsolete. It is also + generally a good idea to note its removal in the release + notes. + + + - - &os; Ports Tree Branches and Layout + + Privacy and Confidentiality - In svn+ssh://repo.freebsd.org/ports, - ports refers to the repository root of - the ports tree. + + + Most &os; business is done in public. - In general, most &os; port work will be done within the - head/ branch of the ports tree which is - the actual ports tree used to install software. Some other - key locations are: + &os; is an open project. Which + means that not only can anyone use the source code, but + that most of the development process is open to public + scrutiny. + + + + Certain sensitive matters must remain private or + held under embargo. + + There unfortunately cannot be complete transparency. + As a &os; developer you will have a certain degree of + privileged access to information. Consequently you are + expected to respect certain requirements for + confidentiality. Sometimes the need for confidentiality + comes from external collaborators or has a specific time + limit. Mostly though, it is a matter of not releasing + private communications. + + + + The Security Officer has sole control over the + release of security advisories. + + Where there are security problems that affect many + different operating systems, &os; frequently depends on + early access in order to be able to prepare advisories for + coordinated release. Unless &os; developers can be + trusted to maintain security, such early access will not + be made available. The Security Officer is responsible + for controlling pre-release access to information about + vulnerabilities, and for timing the release of all + advisories. He may request help under condition of + confidentiality from any developer with relevant knowledge + in order to prepare security fixes. + + + + Communications with Core are kept confidential for as + long as necessary. + + Communications to core will initially be treated as + confidential. Eventually however, most of Core's business + will be summarized into the monthly or quarterly core + reports. Care will be taken to avoid publicising any + sensitive details. Records of some particularly sensitive + subjects may not be reported on at all and will be + retained only in Core's private archives. + + + + Non-disclosure Agreements may be required for access + to certain commercially sensitive data. + + Access to certain commercially sensitive data may + only be available under a Non-Disclosure Agreement. The + FreeBSD Foundation legal staff must be consulted before + any binding agreements are entered into. + + + + Private communications should not be made + public without permission. + + Beyond the specific requirements above there is a + general expectation not to publish private communications + between developers without the consent of all parties + involved. Ask permission before forwarding a message onto + a public mailing list, or posting it to a forum or website + that can be accessed by other than the original + correspondents. + + + + Communications on project-only or restricted access + channels should be treated as private. + + Similarly to personal communications, certain + internal communications channels, including &os; Committer + only mailing lists and restricted access IRC channels + should be considered as private communications. You need + permission in order to publish material from these + sources. + + + + Core may approve publication. + + Where it is impractical to obtain permission due to + the number of correspondents or where permission to + publish is unreasonably withheld, Core may approve release + of such private matters that merit more general + publication. + + + + - - - /branches/RELENG_n_n_n - which corresponds to - RELENG_n_n_n - is used to merge back security updates in preparation - for a release. - + + Developer Relations - - /tags/RELEASE_n_n_n - which corresponds to - RELEASE_n_n_n - represents a release tag of the ports tree. - + If you are 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. If you see 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. If, however, you are + about to modify something which is clearly being actively + maintained by someone else (and it is only by watching the + repository-committers + mailing list that you can really get a feel for just what is and + is not) then consider sending the change to them instead, just + as you would have before becoming a committer. For ports, you + should contact the listed MAINTAINER in the + Makefile. For other parts of the + repository, if you are unsure who the active maintainer might + be, it may help to 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 + ~eadler/bin/whodid. If your queries go + unanswered or the committer otherwise indicates a lack of + interest in the area affected, go ahead and commit it. - - /tags/RELEASE_n_EOL - represents the end of life tag of a specific &os; - branch. - - - - + + Avoid sending private emails to maintainers. Other people + might be interested in the conversation, not just the final + output. + - - Daily Use + If you are unsure about a commit for any reason at all, have + it reviewed by -hackers before committing. + Better to have it flamed then and there rather than when it is + part of the repository. If you do happen to commit something + which results in controversy erupting, you may also wish to + consider backing the change out again until the matter is + settled. Remember – with a version control system we can + always change it back. - This section will explain how to perform common day-to-day - operations with Subversion. + Do not impugn the intentions of someone you disagree with. + If they see a different solution to a problem than you, or even + a different problem, it is not because they are stupid, because + they have questionable parentage, or because they are trying to + destroy your hard work, personal image, or &os;, but simply + because they have a different outlook on the world. Different + is good. - - Help + Disagree honestly. Argue your position from its merits, + be honest about any shortcomings it may have, and be open to + seeing their solution, or even their vision of the problem, + with an open mind. - SVN has built in help documentation. - It can be accessed by typing the following command: + Accept correction. We are all fallible. When you have made + a mistake, apologize and get on with life. Do not beat up + yourself, and certainly do not beat up others for your mistake. + Do not waste time on embarrassment or recrimination, just fix + the problem and move on. - &prompt.user; svn help + Ask for help. Seek out (and give) peer reviews. One of + the ways open source software is supposed to excel is in the + number of eyeballs applied to it; this does not apply if nobody + will review code. + - Additional information can be found in the - Subversion - Book. - + + If in Doubt... - - Checkout + When you are not sure about something, whether it be a + technical issue or a project convention be sure to ask. If you + stay silent you will never make progress. - As seen earlier, to check out the &os; head - branch: + If it relates to a technical issue ask on the public + mailing lists. Avoid the temptation to email the individual + person that knows the answer. This way everyone will be able to + learn from the question and the answer. - &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + For project specific or administrative questions you should + ask, in order: - At some point, more than just HEAD - will probably be useful, for instance when merging changes - to stable/7. Therefore, it may be useful to have a partial - checkout of the complete tree (a full checkout would be very - painful). + + + Your mentor or former mentor. + - To do this, first check out the root of the - repository: + + An experienced committer on IRC, email, etc. + - &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base + + Any team with a "hat", as they should give you a + definitive answer. + - This will give base with all the - files it contains (at the time of writing, just - ROADMAP.txt) and empty subdirectories - for head, stable, - vendor and so on. + + If still not sure, ask on &a.developers;. + + - Expanding the working copy is possible. Just change the - depth of the various subdirectories: + Once your question is answered, if no one pointed you to + documentation that spelled out the answer to your question, + document it, as others will have the same question. + - &prompt.user; svn up --set-depth=infinity base/head -&prompt.user; svn up --set-depth=immediates base/release base/releng base/stable + + Support for Multiple Architectures - The above command will pull down a full copy of - head, plus empty copies of every - release tag, every - releng branch, and every - stable branch. + &os; is a highly portable operating system intended to + function on many different types of hardware architectures. + Maintaining clean separation of Machine Dependent (MD) and + Machine Independent (MI) code, as well as minimizing MD code, is + an important part of our strategy to remain agile with regards + to current hardware trends. Each new hardware architecture + supported by &os; adds substantially to the cost of code + maintenance, toolchain support, and release engineering. It + also dramatically increases the cost of effective testing of + kernel changes. As such, there is strong motivation to + differentiate between classes of support for various + architectures while remaining strong in a few key architectures + that are seen as the &os; target audience. - If at a later date merging to - 7-STABLE is required, expand the working - copy: + + Policy on Multiple Architectures - &prompt.user; svn up --set-depth=infinity base/stable/7 + &os; has added several new architecture ports during + recent release cycles and is truly no longer an &i386; centric + operating system. In an effort to make it easier to keep + &os; portable across the platforms we support, core has + developed the following mandate: - Subtrees do not have to be expanded completely. For - instance, expanding only stable/7/sys and - then later expand the rest of - stable/7: +
+ Our 32-bit reference platform is &arch.i386;, and our + 64-bit reference platform is &arch.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. +
- &prompt.user; svn up --set-depth=infinity base/stable/7/sys -&prompt.user; svn up --set-depth=infinity base/stable/7 + The &arch.i386; and &arch.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. - Updating the tree with svn update - will only update what was previously asked for (in this - case, head and - stable/7; it will not pull down the whole - tree. + We will continue to re-evaluate this policy as cost and + availability of the 64-bit platforms change. - - Decreasing the depth of a working copy is not - possible. - - + 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. + - - Anonymous Checkout + + Statement of General Intent - It is possible to anonymously check out the &os; - repository with Subversion. This will give access to a - read-only tree that can be updated, but not committed back - to the main repository. To do this, use the following - command: + The &os; Project targets "production quality commercial + off-the-shelf (COTS) workstation, server, and high-end + embedded systems". By retaining a focus on a narrow set of + architectures of interest in these environments, the &os; + Project is able to maintain high levels of quality, stability, + and performance, as well as minimize the load on various + support teams on the project, such as the ports team, + documentation team, security officer, and release engineering + teams. Diversity in hardware support broadens the options for + &os; consumers by offering new features and usage + opportunities (such as support for 64-bit CPUs, use in + embedded environments, etc.), but these benefits must always + be carefully considered in terms of the real-world maintenance + cost associated with additional platform support. - &prompt.user; svn co https://svn.FreeBSD.org/base/head /usr/src + The &os; Project differentiates platform targets into + four tiers. Each tier includes a specification of the + requirements for an architecture to be in that tier, + as well as specifying the obligations of developers with + regards to the platform. In addition, a policy is defined + regarding the circumstances required to change the tier + of an architecture. + - More details on using Subversion this way can be found - in Using - Subversion. - + + Tier 1: Fully Supported Architectures - - Updating the Tree + Tier 1 platforms are fully supported by the security + officer, release engineering, and toolchain maintenance staff. + New features added to the operating system must be fully + functional across all Tier 1 architectures for every release + (features which are inherently architecture-specific, such as + support for hardware device drivers, may be exempt from this + requirement). In general, all Tier 1 platforms must have + build and Tinderbox support either in the FreeBSD.org cluster, + or be easily available for all developers. Embedded platforms + may substitute an emulator available in the &os; cluster + for actual hardware. - To update a working copy to either the latest revision, - or a specific revision: + Tier 1 architectures are expected to be Production Quality + with respects to all aspects of the &os; operating system, + including installation and development environments. - &prompt.user; svn update -&prompt.user; svn update -r12345 - + Tier 1 architectures are expected to be completely + integrated into the source tree and have all features + necessary to produce an entire system relevant for that target + architecture. Tier 1 architectures generally have at least 6 + active developers. - - Status + Tier 1 architectures are expected to be fully supported by + the ports system. All the ports should build on a Tier 1 + platform, or have the appropriate filters to prevent the + inappropriate ones from building there. The packaging system + must support all Tier 1 architectures. To ensure an + architecture's Tier 1 status, proponents of that architecture + must show that all relevant packages can be built on that + platform. - To view the local changes that have been made to the - working copy: + Tier 1 embedded architectures must be able to cross-build + packages on at least one other Tier 1 architecture. The + packages must be the most relevant for the platform, but may + be a non-empty subset of those that build natively. - &prompt.user; svn status + Tier 1 architectures must be fully documented. All basic + operations need to be covered by the handbook or other + documents. All relevant integration documentation must also + be integrated into the tree, or readily available. - To show local changes and files that are out-of-date - do: + Current Tier 1 platforms are &arch.i386; and + &arch.amd64;. + - &prompt.user; svn status --show-updates - + + Tier 2: Developmental Architectures - - Editing and Committing + Tier 2 platforms are not supported by the security officer + and release engineering teams. Platform maintainers are + responsible for toolchain support in the tree. The toolchain + maintainers are expected to work with the platform maintainers + to refine these changes. Major new toolchain components are + allowed to break support for Tier 2 architectures if the + &os;-local changes have not been incorporated upstream. + The toolchain maintainers are expected to provide prompt + review of any proposed changes and cannot block, through their + inaction, changes going into the tree. New features added to + &os; should be feasible to implement on these platforms, + but an implementation is not required before the feature may + be added to the &os; source tree. New features that may be + difficult to implement on Tier 2 architectures should provide + a means of disabling them on those architectures. The + implementation of a Tier 2 architecture may be committed to + the main &os; tree as long as it does not interfere with + production work on Tier 1 platforms, or substantially with + other Tier 2 platforms. Before a Tier 2 platform can be added + to the &os; base source tree, the platform must be able to + boot multi-user on actual hardware. Generally, there must be + at least three active developers working on the + platform. - Unlike Perforce, SVN does not need to - be told in advance about file editing. + Tier 2 architectures are usually systems targeted at Tier + 1 support, but that are still under development. + Architectures reaching end of life may also be moved from Tier + 1 status to Tier 2 status as the availability of resources to + continue to maintain the system in a Production Quality state + diminishes. Well supported niche architectures may also be + Tier 2. - To commit all changes in - the current directory and all subdirectories: + Tier 2 architectures have basic support for them + integrated into the ports infrastructure. They may have cross + compilation support added, at the discretion of portmgr. Some + ports must built natively into packages if the package system + supports that architecture. If not integrated into the base + system, some external patches for the architecture for ports + must be available. - &prompt.user; svn commit + Tier 2 architectures can be integrated into the &os; + handbook. The basics for how to get a system running must be + documented, although not necessarily for every single board or + system a Tier 2 architecture supports. The supported hardware + list must exist and should be relatively recent. It should be + integrated into the &os; documentation. - To commit all changes in, for example, - lib/libfetch/ - and - usr/bin/fetch/ - in a single operation: + Current Tier 2 platforms are &arch.arm;, &arch.arm64;, + &arch.ia64; (through &os; 10), + &arch.pc98;, &arch.powerpc;, and &arch.sparc64;. + - &prompt.user; svn commit lib/libfetch usr/bin/fetch + + Tier 3: Experimental Architectures - There is also a commit wrapper for the ports tree to - handle the properties and sanity checking your - changes: + Tier 3 platforms are not supported by the security officer + and release engineering teams. At the discretion of the + toolchain maintainers, they may be supported in the toolchain. + Tier 3 platforms are architectures in the early stages of + development, for non-mainstream hardware platforms, or which + are considered legacy systems unlikely to see broad future + use. Initial support for Tier 3 platforms should be worked on + in external SCM repositories. + The transition to &os;'s subversion should take place after + the platform boots multi-user on hardware; sharing via + subversion is needed for wider exposure; and multiple + developers are actively working on the platform. + Platforms that transition to Tier 3 status may be + removed from the tree if they are no longer actively supported + by the &os; developer community at the discretion of the + release engineer. - &prompt.user; /usr/ports/Tools/scripts/psvn commit - + Tier 3 platforms may have ports support, either integrated + or external, but do not require it. - - Adding and Removing Files + Tier 3 platforms must have the basics documented for how + to build a kernel and how to boot it on at least one target + hardware or emulation environment. This documentation need + not be integrated into the &os; tree. - - Before adding files, get a copy of auto-props.txt - (there is also a - ports tree specific version) and add it to - ~/.subversion/config according to the - instructions in the file. If you added something before - reading this, use svn rm --keep-local - for just added files, fix your config file and re-add them - again. The initial config file is created when you first - run a svn command, even something as simple as - svn help. - - - Files are added to a - SVN repository with svn - add. To add a file named - foo, edit it, then: + Current Tier 3 platforms are &arch.mips;, and + &arch.riscv;. + - &prompt.user; svn add foo + + Tier 4: Unsupported Architectures - - Most new source files should include a - $&os;$ string near the - start of the file. On commit, svn will - expand the $&os;$ string, - adding the file path, revision number, date and time of - commit, and the username of the committer. Files which - cannot be modified may be committed without the - $&os;$ string. - + Tier 4 systems are not supported in any form by the + project. - Files can be removed with svn - remove: + All systems not otherwise classified into a support tier + are Tier 4 systems. The &arch.ia64; platform is transitioning + to Tier 4 status in &os; 11. + - &prompt.user; svn remove foo + + Policy on Changing the Tier of an Architecture - Subversion does not require deleting the file before - using svn rm, and indeed complains if - that happens. + Systems may only be moved from one tier to another by + approval of the &os; Core Team, which shall make that + decision in collaboration with the Security Officer, Release + Engineering, and toolchain maintenance teams. + + - It is possible to add directories with - svn add: + + Subversion Primer - &prompt.user; mkdir bar -&prompt.user; svn add bar + It is assumed that you are already familiar with the basic + operation of Subversion. If not, start by reading the + Subversion + Book. - Although svn mkdir makes this easier - by combining the creation of the directory and the adding of - it: + + Introduction - &prompt.user; svn mkdir bar + The &os; source repository switched from + CVS to Subversion on May 31st, 2008. The + first real SVN commit is + r179447. - Like files, directories are removed with - svn rm. There is no separate command - specifically for removing directories. + The &os; doc/www repository switched + from CVS to Subversion on May 19th, 2012. + The first real SVN commit is + r38821. - &prompt.user; svn rm bar - + The &os; ports repository switched + from CVS to Subversion on July 14th, 2012. + The first real SVN commit is + r300894. - - Copying and Moving Files + Subversion can be installed from the &os; Ports + Collection by issuing these commands: - This command creates a copy of - foo.c named bar.c, - with the new file also under version control: + &prompt.root; pkg install subversion - &prompt.user; svn copy foo.c bar.c + - The example above is equivalent to: + + Getting Started - &prompt.user; cp foo.c bar.c -&prompt.user; svn add bar.c + There are a few ways to obtain a working copy of the tree + from Subversion. This section will explain them. - To move and rename a file: + + Direct Checkout - &prompt.user; svn move foo.c bar.c - + The first is to check out directly from the main + repository. For the src tree, + use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src + + For the doc tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc + + For the ports tree, use: + + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports + + + Though the remaining examples in this document are + written with the workflow of working with the + src tree in mind, the underlying + concepts are the same for working with the + doc and the ports + tree. + Ports related Subversion operations are listed in + . + + + The above command will check out a + CURRENT source tree as + /usr/src/, + which can be any target directory on the local filesystem. + Omitting the final argument of that command causes the + working copy, in this case, to be named head, + but that can be renamed safely. + + svn+ssh means the + SVN protocol tunnelled over + SSH. The name of the server is + repo.freebsd.org, base + is the path to the repository, and head + is the subdirectory within the repository. + + If your &os; login name is different from your login + name on your local machine, you must either include it in + the URL (for example + svn+ssh://jarjar@repo.freebsd.org/base/head), + or add an entry to your ~/.ssh/config + in the form: - - Log and Annotate + Host repo.freebsd.org + User jarjar - svn log shows revisions and commit - messages, most recent first, for files or directories. When - used on a directory, all revisions that affected the - directory and files within that directory are shown. + This is the simplest method, but it is hard to tell just + yet how much load it will place on the repository. - svn annotate, or equally svn - praise or svn blame, shows - the most recent revision number and who committed that - revision for each line of a file. + + The svn diff does not require + access to the server as SVN stores a + reference copy of every file in the working copy. This, + however, means that Subversion working copies are very + large in size. + - - Diffs - - svn diff displays changes to the - working copy. Diffs generated by SVN are - unified and include new files by default in the diff - output. - - svn diff can show the changes between - two revisions of the same file: - - &prompt.user; svn diff -r179453:179454 ROADMAP.txt - - It can also show all changes for a specific changeset. - The following will show what changes were made to the - current directory and all subdirectories in changeset - 179454: + + Checkout from a Mirror - &prompt.user; svn diff -c179454 . - + Check out a working copy from a mirror by + substituting the mirror's URL for + svn+ssh://repo.freebsd.org/base. This + can be an official mirror or a mirror maintained by using + svnsync. - - Reverting + There is a serious disadvantage to this method: every + time something is to be committed, a + svn relocate to the master repository has + to be done, remembering to svn relocate + back to the mirror after the commit. Also, since + svn relocate only works between + repositories that have the same UUID, some hacking of the + local repository's UUID has to occur before it is possible + to start using it. - Local changes (including additions and deletions) can be - reverted using svn revert. It does not - update out-of-date files, but just replaces them with - pristine copies of the original version. + The hassle of a local + svnsync mirror probably is not worth it + unless the network connectivity situation or other factors + demand it. If it is needed, see the end of this chapter for + information on how to set one up. - - Conflicts - - If an svn update resulted in a merge - conflict, Subversion will remember which files have - conflicts and refuse to commit any changes to those files - until explicitly told that the conflicts have been resolved. - The simple, not yet deprecated procedure is the - following: + + <literal>RELENG_*</literal> Branches and General + Layout - &prompt.user; svn resolved foo + In svn+ssh://repo.freebsd.org/base, + base refers to the source tree. + Similarly, ports refers to the ports + tree, and so on. These are separate repositories with their + own change number sequences, access controls and commit + mail. - However, the preferred procedure is: + For the base repository, HEAD refers to the -CURRENT + tree. For example, head/bin/ls is what + would go into /usr/src/bin/ls in a + release. Some key locations are: - &prompt.user; svn resolve --accept=working foo + + + /head/ which corresponds to + HEAD, also known as + -CURRENT. + - The two examples are equivalent. Possible values for - --accept are: + + /stable/n + which corresponds to + RELENG_n. + - - working: use the version in your - working directory (which one presumes has been edited to - resolve the conflicts). + /releng/n.n + which corresponds to + RELENG_n_n. - base: use a pristine copy of the - version you had before svn update, - discarding your own changes, the conflicting changes, - and possibly other intervening changes as well. + /release/n.n.n + which corresponds to + RELENG_n_n_n_RELEASE. - mine-full: use what you had - before svn update, including your own - changes, but discarding the conflicting changes, and - possibly other intervening changes as well. + /vendor* is the vendor branch + import work area. This directory itself does not + contain branches, however its subdirectories do. This + contrasts with the stable, + releng and + release directories. - theirs-full: use the version that - was retrieved when you did - svn update, discarding your own - changes. + /projects and + /user feature a branch work area, + like in Perforce. As above, the + /user directory does not contain + branches itself. - - - Advanced Use + + &os; Documentation Project Branches and + Layout - - Sparse Checkouts + In svn+ssh://repo.freebsd.org/doc, + doc refers to the repository root of + the source tree. - SVN allows - sparse, or partial checkouts of a - directory by adding to a - svn checkout. + In general, most &os; Documentation Project work will be + done within the head/ branch of the + documentation source tree. - Valid arguments to - are: + &os; documentation is written and/or translated to + various languages, each in a separate + directory in the head/ + branch. + + Each translation set contains several subdirectories for + the various parts of the &os; Documentation Project. A few + noteworthy directories are: - empty: the directory itself - without any of its contents. + /articles/ contains the source + code for articles written by various &os; + contributors. - files: the directory and any - files it contains. + /books/ contains the source + code for the different books, such as the + &os; Handbook. - immediates: the directory and any - files and directories it contains, but none of the - subdirectories' contents. - - - - infinity: anything. + /htdocs/ contains the source + code for the &os; website. - - The --depth option applies to many - other commands, including svn commit, - svn revert, and svn - diff. - - Since --depth is sticky, there is a - --set-depth option for svn - update that will change the selected depth. - Thus, given the working copy produced by the previous - example: - - &prompt.user; cd ~/freebsd -&prompt.user; svn update --set-depth=immediates . - - The above command will populate the working copy in - ~/freebsd with - ROADMAP.txt and empty subdirectories, - and nothing will happen when svn update - is executed on the subdirectories. However, the following - command will set the depth for - head (in this case) to infinity, - and fully populate it: - - &prompt.user; svn update --set-depth=infinity head - - Direct Operation + + &os; Ports Tree Branches and Layout - Certain operations can be performed directly on the - repository without touching the working copy. Specifically, - this applies to any operation that does not require editing - a file, including: + In svn+ssh://repo.freebsd.org/ports, + ports refers to the repository root of + the ports tree. + + In general, most &os; port work will be done within the + head/ branch of the ports tree which is + the actual ports tree used to install software. Some other + key locations are: - log, - diff + /branches/RELENG_n_n_n + which corresponds to + RELENG_n_n_n + is used to merge back security updates in preparation + for a release. - mkdir + /tags/RELEASE_n_n_n + which corresponds to + RELEASE_n_n_n + represents a release tag of the ports tree. - remove, copy, - rename + /tags/RELEASE_n_EOL + represents the end of life tag of a specific &os; + branch. + + + - - propset, - propedit, - propdel - + + Daily Use - - merge - - + This section will explain how to perform common day-to-day + operations with Subversion. - Branching is very fast. The following command would be - used to branch RELENG_8: + + Help - &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8 + SVN has built in help documentation. + It can be accessed by typing the following command: - This is equivalent to the following set of commands - which take minutes and hours as opposed to seconds, - depending on your network connection: + &prompt.user; svn help - &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base -&prompt.user; cd base -&prompt.user; svn update --set-depth=infinity head -&prompt.user; svn copy head stable/8 -&prompt.user; svn commit stable/8 + Additional information can be found in the + Subversion + Book. - - Merging with <acronym>SVN</acronym> + + Checkout - This section deals with merging code from one branch to - another (typically, from head to a stable branch). + As seen earlier, to check out the &os; head + branch: - - In all examples below, $FSVN - refers to the location of the &os; Subversion repository, - svn+ssh://repo.freebsd.org/base/. - + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src - - About Merge Tracking + At some point, more than just HEAD + will probably be useful, for instance when merging changes + to stable/7. Therefore, it may be useful to have a partial + checkout of the complete tree (a full checkout would be very + painful). - From the user's perspective, merge tracking - information (or mergeinfo) is stored in a property called - svn:mergeinfo, which is a - comma-separated list of revisions and ranges of revisions - that have been merged. When set on a file, it applies - only to that file. When set on a directory, it applies to - that directory and its descendants (files and directories) - except for those that have their own - svn:mergeinfo. + To do this, first check out the root of the + repository: - It is not inherited. For - instance, stable/6/contrib/openpam/ - does not implicitly inherit mergeinfo from - stable/6/, or - stable/6/contrib/. - Doing so would make partial checkouts very hard to manage. - Instead, mergeinfo is explicitly propagated down the tree. - For merging something into - branch/foo/bar/, - the following rules apply: + &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base - - - If - branch/foo/bar/ - does not already have a mergeinfo record, but a direct - ancestor (for instance, - branch/foo/) - does, then that record will be propagated down to - branch/foo/bar/ - before information about the current merge is - recorded. - + This will give base with all the + files it contains (at the time of writing, just + ROADMAP.txt) and empty subdirectories + for head, stable, + vendor and so on. - - Information about the current merge will - not be propagated back up that - ancestor. - + Expanding the working copy is possible. Just change the + depth of the various subdirectories: - - If a direct descendant of - branch/foo/bar/ (for instance, - branch/foo/bar/baz/) already has - a mergeinfo record, information about the current - merge will be propagated down to it. - - + &prompt.user; svn up --set-depth=infinity base/head +&prompt.user; svn up --set-depth=immediates base/release base/releng base/stable - If you consider the case where a revision changes - several separate parts of the tree (for example, - branch/foo/bar/ and - branch/foo/quux/), but you only want - to merge some of it (for example, - branch/foo/bar/), you will see that - these rules make sense. If mergeinfo was propagated up, - it would seem like that revision had also been merged to - branch/foo/quux/, when in fact it had - not been. - + The above command will pull down a full copy of + head, plus empty copies of every + release tag, every + releng branch, and every + stable branch. - - Selecting the Source and Target Branch - When Merging + If at a later date merging to + 7-STABLE is required, expand the working + copy: - Merging to stable/ branches should - originate from head/. For - example: + &prompt.user; svn up --set-depth=infinity base/stable/7 - &prompt.user; svn merge -c r123456 ^/head/ stable/11 -&prompt.user; svn commit stable/11 + Subtrees do not have to be expanded completely. For + instance, expanding only stable/7/sys and + then later expand the rest of + stable/7: - - Note the sections below which outline changes to - the target location of the stable/ - branch starting with - stable/10. - + &prompt.user; svn up --set-depth=infinity base/stable/7/sys +&prompt.user; svn up --set-depth=infinity base/stable/7 - Merges to releng/ branches should - always originate from the corresponding - stable/ branch. For example: + Updating the tree with svn update + will only update what was previously asked for (in this + case, head and + stable/7; it will not pull down the whole + tree. - &prompt.user; svn merge -c r123456 ^/stable/11 releng/11.0 -&prompt.user; svn commit releng/11.0 + + Decreasing the depth of a working copy is not + possible. + + - - Committers are only permitted to commit to the - releng/ branches during a release - cycle after receiving approval from the Release - Engineering Team, after which only the Security Officer - may commit to a releng/ branch for - a Security Advisory or Errata Notice. - - + + Anonymous Checkout - - Selecting the Source and Target for - <literal>stable/10</literal> and Newer + It is possible to anonymously check out the &os; + repository with Subversion. This will give access to a + read-only tree that can be updated, but not committed back + to the main repository. To do this, use the following + command: - Starting with the stable/10 - branch, all merges should be - merged to and committed from the root of the - branch. All merges should look like: + &prompt.user; svn co http://svn.freebsd.org/base/head /usr/src - &prompt.user; svn merge -c r123456 ^/head/ checkout -&prompt.user; svn commit checkout + More details on using Subversion this way can be found + in Using + Subversion. + - Note that checkout should - be a complete checkout of the branch to which the merge - occurs. - + + Updating the Tree - - Selecting the Source and Target for - <literal>stable/9</literal> and Older + To update a working copy to either the latest revision, + or a specific revision: - For stable/9 and earlier, - a different strategy was used, distributing mergeinfo - around the tree so that merges could be performed without - a complete checkout. This procedure proved extremely - error-prone, with the convenience of partial checkouts for - merges significantly outweighed by the complexity of - picking mergeinfo targets. The below describes this - now-obsoleted procedure, which should be used - only for merges prior to - stable/10. + &prompt.user; svn update +&prompt.user; svn update -r12345 + - Because of mergeinfo propagation, it is important to - choose the source and target for the merge carefully to - minimise property changes on unrelated directories. + + Status - The rules for selecting the merge target (the - directory that you will merge the changes to) can be - summarized as follows: + To view the local changes that have been made to the + working copy: - - - Never merge directly to a file. - + &prompt.user; svn status - - Never, ever merge directly to a file. - + To show local changes and files that are out-of-date + do: - - Never, ever, ever merge - directly to a file. - + &prompt.user; svn status --show-updates + - - Changes to kernel code should be merged to - sys/. For instance, a change to - the &man.ichwd.4; driver should be merged to - sys/, not - sys/dev/ichwd/. Likewise, a - change to the TCP/IP stack should be merged to - sys/, not - sys/netinet/. - + + Editing and Committing - - Changes to code under etc/ - should be merged at etc/, not - below it. - + Unlike Perforce, SVN does not need to + be told in advance about file editing. - - Changes to vendor code (code in - contrib/, - crypto/ and so on) should be - merged to the directory where vendor imports happen. - For instance, a change to - crypto/openssl/util/ should be - merged to crypto/openssl/. This - is rarely an issue, however, since changes to vendor - code are usually merged wholesale. - + To commit all changes in + the current directory and all subdirectories: - - Changes to userland programs should as a general - rule be merged to the directory that contains the - Makefile for that program. For instance, a change to - usr.bin/xlint/arch/i386/ should - be merged to - usr.bin/xlint/. - + &prompt.user; svn commit - - Changes to userland libraries should as a general - rule be merged to the directory that contains the - Makefile for that library. For instance, a change to - lib/libc/gen/ should be merged to - lib/libc/. - + To commit all changes in, for example, + lib/libfetch/ + and + usr/bin/fetch/ + in a single operation: - - There may be cases where it makes sense to deviate - from the rules for userland programs and libraries. - For instance, everything under - lib/libpam/ is merged to - lib/libpam/, even though the - library itself and all of the modules each have their - own Makefile. - + &prompt.user; svn commit lib/libfetch usr/bin/fetch - - Changes to manual pages should be merged to - share/man/manN/, - for the appropriate value of - N. - + There is also a commit wrapper for the ports tree to + handle the properties and sanity checking your + changes: - - Other changes to share/ - should be merged to the appropriate subdirectory and - not to share/ directly. - + &prompt.user; /usr/ports/Tools/scripts/psvn commit + - - Changes to a top-level file in the source tree - such as UPDATING or - Makefile.inc1 should be merged - directly to that file rather than to the root of the - whole tree. Yes, this is an exception to the first - three rules. - + + Adding and Removing Files - - When in doubt, ask. - - + + Before adding files, get a copy of auto-props.txt + (there is also a + ports tree specific version) and add it to + ~/.subversion/config according to the + instructions in the file. If you added something before + reading this, use svn rm --keep-local + for just added files, fix your config file and re-add them + again. The initial config file is created when you first + run a svn command, even something as simple as + svn help. + - If you need to merge changes to several places at once - (for instance, changing a kernel interface and every - userland program that uses it), merge each target - separately, then commit them together. For instance, if - you merge a revision that changed a kernel - API and updated all the userland bits - that used that API, you would merge the - kernel change to sys, and the userland bits to the - appropriate userland directories, then commit all of these - in one go. + Files are added to a + SVN repository with svn + add. To add a file named + foo, edit it, then: - The source will almost invariably be the same as the - target. For instance, you will always merge - stable/7/lib/libc/ from - head/lib/libc/. The only exception - would be when merging changes to code that has moved in - the source branch but not in the parent branch. For - instance, a change to &man.pkill.1; would be merged from - bin/pkill/ in head to - usr.bin/pkill/ in stable/7. - + &prompt.user; svn add foo - - Preparing the Merge Target + + Most new source files should include a + $&os;$ string near the + start of the file. On commit, svn will + expand the $&os;$ string, + adding the file path, revision number, date and time of + commit, and the username of the committer. Files which + cannot be modified may be committed without the + $&os;$ string. + - Because of the mergeinfo propagation issues described - earlier, it is very important that you never merge changes - into a sparse working copy. You must always have a full - checkout of the branch you will merge into. For instance, - when merging from HEAD to 7, you must have a full checkout - of stable/7: + Files can be removed with svn + remove: - &prompt.user; cd stable/7 -&prompt.user; svn up --set-depth=infinity + &prompt.user; svn remove foo - The target directory must also be up-to-date and must - not contain any uncommitted changes or stray files. - + Subversion does not require deleting the file before + using svn rm, and indeed complains if + that happens. - - Identifying Revisions + It is possible to add directories with + svn add: - Identifying revisions to be merged is a must. If the - target already has complete mergeinfo, ask - SVN for a list: + &prompt.user; mkdir bar +&prompt.user; svn add bar - &prompt.user; cd stable/6/contrib/openpam -&prompt.user; svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam + Although svn mkdir makes this easier + by combining the creation of the directory and the adding of + it: - If the target does not have complete mergeinfo, check - the log for the merge source. - + &prompt.user; svn mkdir bar - - Merging + Like files, directories are removed with + svn rm. There is no separate command + specifically for removing directories. - Now, let us start merging! + &prompt.user; svn rm bar + - - The Principles + + Copying and Moving Files - Say you would like to merge: + This command creates a copy of + foo.c named bar.c, + with the new file also under version control: - - - revision $R - + &prompt.user; svn copy foo.c bar.c - - in directory $target in stable branch - $B - + The example above is equivalent to: - - from directory $source in head - + &prompt.user; cp foo.c bar.c +&prompt.user; svn add bar.c - - $FSVN is - svn+ssh://repo.freebsd.org/base - - + To move and rename a file: - Assuming that revisions $P and $Q have - already been merged, and that the current directory is - an up-to-date working copy of stable/$B, the - existing mergeinfo looks like this: + &prompt.user; svn move foo.c bar.c + - &prompt.user; svn propget svn:mergeinfo -R $target -$target - /head/$source:$P,$Q + + Log and Annotate - Merging is done like so: + svn log shows revisions and commit + messages, most recent first, for files or directories. When + used on a directory, all revisions that affected the + directory and files within that directory are shown. - &prompt.user; svn merge -c$R $FSVN/head/$source $target + svn annotate, or equally svn + praise or svn blame, shows + the most recent revision number and who committed that + revision for each line of a file. + - Checking the results of this is possible with - svn diff. + + Diffs - The svn:mergeinfo now looks like: + svn diff displays changes to the + working copy. Diffs generated by SVN are + unified and include new files by default in the diff + output. - &prompt.user; svn propget svn:mergeinfo -R $target -$target - head/$source:$P,$Q,$R + svn diff can show the changes between + two revisions of the same file: - If the results are not exactly as shown, assistance - may be required before committing as mistakes may have - been made, or there may be something wrong with the - existing mergeinfo, or there may be a bug in - Subversion. - + &prompt.user; svn diff -r179453:179454 ROADMAP.txt - - Practical Example + It can also show all changes for a specific changeset. + The following will show what changes were made to the + current directory and all subdirectories in changeset + 179454: - As a practical example, consider the following - scenario. The changes to netmap.4 - in r238987 are to be merged from CURRENT to 9-STABLE. - The file resides in - head/share/man/man4. According - to , this is - also where to do the merge. Note that in this example - all paths are relative to the top of the svn repository. - For more information on the directory layout, see . + &prompt.user; svn diff -c179454 . + - The first step is to inspect the existing - mergeinfo. + + Reverting - &prompt.user; svn propget svn:mergeinfo -R stable/9/share/man/man4 + Local changes (including additions and deletions) can be + reverted using svn revert. It does not + update out-of-date files, but just replaces them with + pristine copies of the original version. + - Take a quick note of how it looks before moving on - to the next step; doing the actual merge: + + Conflicts - &prompt.user; svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4 ---- Merging r238987 into 'stable/9/share/man/man4': -U stable/9/share/man/man4/netmap.4 ---- Recording mergeinfo for merge of r238987 into -'stable/9/share/man/man4': - U stable/9/share/man/man4 + If an svn update resulted in a merge + conflict, Subversion will remember which files have + conflicts and refuse to commit any changes to those files + until explicitly told that the conflicts have been resolved. + The simple, not yet deprecated procedure is the + following: - Check that the revision number of the merged - revision has been added. Once this is verified, the - only thing left is the actual commit. + &prompt.user; svn resolved foo - &prompt.user; svn commit stable/9/share/man/man4 - + However, the preferred procedure is: - - Merging into the Kernel - (<filename>sys/</filename>) + &prompt.user; svn resolve --accept=working foo - As stated above, merging into the kernel is - different from merging in the rest of the tree. In many - ways merging to the kernel is simpler because there is - always the same merge target - (sys/). + The two examples are equivalent. Possible values for + --accept are: - Once svn merge has been executed, - svn diff has to be run on the - directory to check the changes. This may show some - unrelated property changes, but these can be ignored. - Next, build and test the kernel, and, once the tests are - complete, commit the code as normal, making sure that - the commit message starts with Merge - r226222 from head, - or similar. - - + + + working: use the version in your + working directory (which one presumes has been edited to + resolve the conflicts). + - - Precautions Before Committing + + base: use a pristine copy of the + version you had before svn update, + discarding your own changes, the conflicting changes, + and possibly other intervening changes as well. + - As always, build world (or appropriate parts of - it). + + mine-full: use what you had + before svn update, including your own + changes, but discarding the conflicting changes, and + possibly other intervening changes as well. + - Check the changes with svn diff and - svn stat. Make sure all the files that - should have been added or deleted were in fact added or - deleted. + + theirs-full: use the version that + was retrieved when you did + svn update, discarding your own + changes. + + + + - Take a closer look at any property change (marked by a - M in the second column of svn - stat). Normally, no svn:mergeinfo properties - should be anywhere except the target directory (or - directories). + + Advanced Use - If something looks fishy, ask for help. - + + Sparse Checkouts - - Committing + SVN allows + sparse, or partial checkouts of a + directory by adding to a + svn checkout. - Make sure to commit a top level directory to have the - mergeinfo included as well. Do not specify individual - files on the command line. For more information about - committing files in general, see the relevant section of - this primer. - - + Valid arguments to + are: - - Vendor Imports with <acronym>SVN</acronym> + + + empty: the directory itself + without any of its contents. + - - Please read this entire section before starting a - vendor import. - + + files: the directory and any + files it contains. + - - Patches to vendor code fall into two - categories: + + immediates: the directory and any + files and directories it contains, but none of the + subdirectories' contents. + - - - Vendor patches: these are patches that have been - issued by the vendor, or that have been extracted from - the vendor's version control system, which address - issues which in your opinion cannot wait until the - next vendor release. - + + infinity: anything. + + - - &os; patches: these are patches that modify the - vendor code to address &os;-specific issues. - - + The --depth option applies to many + other commands, including svn commit, + svn revert, and svn + diff. - The nature of a patch dictates where it should be - committed: + Since --depth is sticky, there is a + --set-depth option for svn + update that will change the selected depth. + Thus, given the working copy produced by the previous + example: - - - Vendor patches should be committed to the vendor - branch, and merged from there to head. If the patch - addresses an issue in a new release that is currently - being imported, it must not be - committed along with the new release: the release must - be imported and tagged first, then the patch can be - applied and committed. There is no need to re-tag the - vendor sources after committing the patch. - + &prompt.user; cd ~/freebsd +&prompt.user; svn update --set-depth=immediates . - - &os; patches should be committed directly to - head. - - - + The above command will populate the working copy in + ~/freebsd with + ROADMAP.txt and empty subdirectories, + and nothing will happen when svn update + is executed on the subdirectories. However, the following + command will set the depth for + head (in this case) to infinity, + and fully populate it: - - Preparing the Tree + &prompt.user; svn update --set-depth=infinity head + - If importing for the first time after the switch to - Subversion, flattening and cleaning up the vendor tree is - necessary, as well as bootstrapping the merge history in - the main tree. + + Direct Operation - - Flattening + Certain operations can be performed directly on the + repository without touching the working copy. Specifically, + this applies to any operation that does not require editing + a file, including: - During the conversion from CVS to - Subversion, vendor branches were imported with the same - layout as the main tree. This means that the - pf vendor sources ended up in - vendor/pf/dist/contrib/pf. The - vendor source is best directly in - vendor/pf/dist. + + + log, + diff + - To flatten the pf tree: + + mkdir + - &prompt.user; cd vendor/pf/dist/contrib/pf -&prompt.user; svn mv $(svn list) ../.. -&prompt.user; cd ../.. -&prompt.user; svn rm contrib -&prompt.user; svn propdel -R svn:mergeinfo . -&prompt.user; svn commit + + remove, copy, + rename + - The propdel bit is necessary - because starting with 1.5, Subversion will automatically - add svn:mergeinfo to any directory - that is copied or moved. In this case, as nothing is - being merged from the deleted tree, they just get in the - way. + + propset, + propedit, + propdel + - Tags may be flattened as well (3, 4, 3.5 etc.); the - procedure is exactly the same, only changing - dist to 3.5 or - similar, and putting the svn commit - off until the end of the process. - + + merge + + - - Cleaning Up + Branching is very fast. The following command would be + used to branch RELENG_8: - The dist tree can be cleaned up - as necessary. Disabling keyword expansion is - recommended, as it makes no sense on unmodified vendor - code and in some cases it can even be harmful. - OpenSSH, for example, - includes two files that originated with &os; and still - contain the original version tags. To do this: + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8 - &prompt.user; svn propdel svn:keywords -R . -&prompt.user; svn commit - + This is equivalent to the following set of commands + which take minutes and hours as opposed to seconds, + depending on your network connection: - - Bootstrapping Merge History + &prompt.user; svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base +&prompt.user; cd base +&prompt.user; svn update --set-depth=infinity head +&prompt.user; svn copy head stable/8 +&prompt.user; svn commit stable/8 + - If importing for the first time after the switch to - Subversion, bootstrap svn:mergeinfo - on the target directory in the main tree to the revision - that corresponds to the last related change to the - vendor tree, prior to importing new sources: + + Merging with <acronym>SVN</acronym> - &prompt.user; cd head/contrib/pf -&prompt.user; svn merge --record-only svn+ssh://repo.freebsd.org/base/vendor/pf/dist@180876 . -&prompt.user; svn commit - - + This section deals with merging code from one branch to + another (typically, from head to a stable branch). - - Importing New Sources + + In all examples below, $FSVN + refers to the location of the &os; Subversion repository, + svn+ssh://repo.freebsd.org/base/. + - With two commits—one for the import itself and - one for the tag—this step can optionally be repeated - for every upstream release between the last import and the - current import. + + About Merge Tracking - - Preparing the Vendor Sources + From the user's perspective, merge tracking + information (or mergeinfo) is stored in a property called + svn:mergeinfo, which is a + comma-separated list of revisions and ranges of revisions + that have been merged. When set on a file, it applies + only to that file. When set on a directory, it applies to + that directory and its descendants (files and directories) + except for those that have their own + svn:mergeinfo. - Unlike in CVS where only the - needed parts were imported into the vendor tree to avoid - bloating the main tree, Subversion is able to store a - full distribution in the vendor tree. So, import - everything, but merge only what is required. + It is not inherited. For + instance, stable/6/contrib/openpam/ + does not implicitly inherit mergeinfo from + stable/6/, or + stable/6/contrib/. + Doing so would make partial checkouts very hard to manage. + Instead, mergeinfo is explicitly propagated down the tree. + For merging something into + branch/foo/bar/, + the following rules apply: - A svn add is required to add any - files that were added since the last vendor import, and - svn rm is required to remove any that - were removed since. Preparing sorted lists of the - contents of the vendor tree and of the sources that are - about to be imported is recommended, to facilitate the - process. + + + If + branch/foo/bar/ + does not already have a mergeinfo record, but a direct + ancestor (for instance, + branch/foo/) + does, then that record will be propagated down to + branch/foo/bar/ + before information about the current merge is + recorded. + - &prompt.user; cd vendor/pf/dist -&prompt.user; svn list -R | grep -v '/$' | sort >../old -&prompt.user; cd ../pf-4.3 -&prompt.user; find . -type f | cut -c 3- | sort >../new + + Information about the current merge will + not be propagated back up that + ancestor. + - With these two files, - comm -23 ../old ../new will list - removed files (files only in old), - while comm -13 ../old ../new will - list added files only in - new. - + + If a direct descendant of + branch/foo/bar/ (for instance, + branch/foo/bar/baz/) already has + a mergeinfo record, information about the current + merge will be propagated down to it. + + - - Importing into the Vendor Tree + If you consider the case where a revision changes + several separate parts of the tree (for example, + branch/foo/bar/ and + branch/foo/quux/), but you only want + to merge some of it (for example, + branch/foo/bar/), you will see that + these rules make sense. If mergeinfo was propagated up, + it would seem like that revision had also been merged to + branch/foo/quux/, when in fact it had + not been. + - Now, the sources must be copied into - dist and - the svn add and - svn rm commands should be used as - needed: + + Selecting the Source and Target Branch + When Merging - &prompt.user; cd vendor/pf/pf-4.3 -&prompt.user; tar cf - . | tar xf - -C ../dist -&prompt.user; cd ../dist -&prompt.user; comm -23 ../old ../new | xargs svn rm -&prompt.user; comm -13 ../old ../new | xargs svn --parents add + Merging to stable/ branches should + originate from head/. For + example: - If any directories were removed, they will have to - be svn rmed manually. Nothing will - break if they are not, but they will remain in the - tree. + &prompt.user; svn merge -c r123456 ^/head/ stable/11 +&prompt.user; svn commit stable/11 - Check properties on any new files. All text files - should have svn:eol-style set to - native. All binary files should have - svn:mime-type set to - application/octet-stream unless there - is a more appropriate media type. Executable files - should have svn:executable set to - *. No other properties should exist - on any file in the tree. + + Note the sections below which outline changes to + the target location of the stable/ + branch starting with + stable/10. + - Committing is now possible, however it is good - practice to make sure that everything is OK by using the - svn stat and - svn diff commands. - + Merges to releng/ branches should + always originate from the corresponding + stable/ branch. For example: - - Tagging + &prompt.user; svn merge -c r123456 ^/stable/11 releng/11.0 +&prompt.user; svn commit releng/11.0 - Once committed, vendor releases should be tagged for - future reference. The best and quickest way to do this - is directly in the repository: + + Committers are only permitted to commit to the + releng/ branches during a release + cycle after receiving approval from the Release + Engineering Team, after which only the Security Officer + may commit to a releng/ branch for + a Security Advisory or Errata Notice. + + - &prompt.user; svn cp svn+ssh://repo.freebsd.org/base/vendor/pf/dist svn+ssh://repo.freebsd.org/base/vendor/pf/4.3 + + Selecting the Source and Target for + <literal>stable/10</literal> and Newer - Once that is complete, svn up the - working copy of - vendor/pf - to get the new tag, although this is rarely - needed. + Starting with the stable/10 + branch, all merges should be + merged to and committed from the root of the + branch. All merges should look like: - If creating the tag in the working copy of the tree, - svn:mergeinfo results must be - removed: + &prompt.user; svn merge -c r123456 ^/head/ checkout +&prompt.user; svn commit checkout - &prompt.user; cd vendor/pf -&prompt.user; svn cp dist 4.3 -&prompt.user; svn propdel svn:mergeinfo -R 4.3 - + Note that checkout should + be a complete checkout of the branch to which the merge + occurs. - - Merging to Head + + Selecting the Source and Target for + <literal>stable/9</literal> and Older - &prompt.user; cd head/contrib/pf -&prompt.user; svn up -&prompt.user; svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/vendor/pf/dist . + For stable/9 and earlier, + a different strategy was used, distributing mergeinfo + around the tree so that merges could be performed without + a complete checkout. This procedure proved extremely + error-prone, with the convenience of partial checkouts for + merges significantly outweighed by the complexity of + picking mergeinfo targets. The below describes this + now-obsoleted procedure, which should be used + only for merges prior to + stable/10. - The --accept=postpone tells - Subversion that it should not complain because merge - conflicts will be taken care of manually. + Because of mergeinfo propagation, it is important to + choose the source and target for the merge carefully to + minimise property changes on unrelated directories. - - The cvs2svn changeover occurred - on June 3, 2008. When performing vendor merges for - packages which were already present and converted by the - cvs2svn process, the command used to - merge - /vendor/package_name/dist - to - /head/package_location - (for example, - head/contrib/sendmail) must use - to - indicate the revision to merge from the - /vendor tree. For example: + The rules for selecting the merge target (the + directory that you will merge the changes to) can be + summarized as follows: - &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/sendmail -&prompt.user; cd sendmail -&prompt.user; svn merge -c r261190 ^/vendor/sendmail/dist . + + + Never merge directly to a file. + - ^ is an alias for the - repository path. - + + Never, ever merge directly to a file. + - - If using the Zsh shell, - the ^ must be escaped with - \. This means - ^/head should be - \^/head. - + + Never, ever, ever merge + directly to a file. + - It is necessary to resolve any merge conflicts. + + Changes to kernel code should be merged to + sys/. For instance, a change to + the &man.ichwd.4; driver should be merged to + sys/, not + sys/dev/ichwd/. Likewise, a + change to the TCP/IP stack should be merged to + sys/, not + sys/netinet/. + - Make sure that any files that were added or removed in - the vendor tree have been properly added or removed in the - main tree. To check diffs against the vendor - branch: + + Changes to code under etc/ + should be merged at etc/, not + below it. + - &prompt.user; svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/vendor/pf/dist --new=. + + Changes to vendor code (code in + contrib/, + crypto/ and so on) should be + merged to the directory where vendor imports happen. + For instance, a change to + crypto/openssl/util/ should be + merged to crypto/openssl/. This + is rarely an issue, however, since changes to vendor + code are usually merged wholesale. + - The --no-diff-deleted tells - Subversion not to complain about files that are in the - vendor tree but not in the main tree, i.e., things that - would have previously been removed before the vendor - import, like for example the vendor's makefiles - and configure scripts. + + Changes to userland programs should as a general + rule be merged to the directory that contains the + Makefile for that program. For instance, a change to + usr.bin/xlint/arch/i386/ should + be merged to + usr.bin/xlint/. + - Using CVS, once a file was off the - vendor branch, it was not able to be put back. With - Subversion, there is no concept of on or off the vendor - branch. If a file that previously had local - modifications, to make it not show up in diffs in the - vendor tree, all that has to be done is remove any - left-over cruft like &os; version tags, which is much - easier. + + Changes to userland libraries should as a general + rule be merged to the directory that contains the + Makefile for that library. For instance, a change to + lib/libc/gen/ should be merged to + lib/libc/. + - If any changes are required for the world to build - with the new sources, make them now, and keep testing - until everything builds and runs perfectly. - + + There may be cases where it makes sense to deviate + from the rules for userland programs and libraries. + For instance, everything under + lib/libpam/ is merged to + lib/libpam/, even though the + library itself and all of the modules each have their + own Makefile. + - - Committing the Vendor Import + + Changes to manual pages should be merged to + share/man/manN/, + for the appropriate value of + N. + - Committing is now possible! Everything must be - committed in one go. If done properly, the tree will move - from a consistent state with old code, to a consistent - state with new code. + + Other changes to share/ + should be merged to the appropriate subdirectory and + not to share/ directly. + + + + Changes to a top-level file in the source tree + such as UPDATING or + Makefile.inc1 should be merged + directly to that file rather than to the root of the + whole tree. Yes, this is an exception to the first + three rules. + + + + When in doubt, ask. + + + + If you need to merge changes to several places at once + (for instance, changing a kernel interface and every + userland program that uses it), merge each target + separately, then commit them together. For instance, if + you merge a revision that changed a kernel + API and updated all the userland bits + that used that API, you would merge the + kernel change to sys, and the userland bits to the + appropriate userland directories, then commit all of these + in one go. + + The source will almost invariably be the same as the + target. For instance, you will always merge + stable/7/lib/libc/ from + head/lib/libc/. The only exception + would be when merging changes to code that has moved in + the source branch but not in the parent branch. For + instance, a change to &man.pkill.1; would be merged from + bin/pkill/ in head to + usr.bin/pkill/ in stable/7. - From Scratch + Preparing the Merge Target - - Importing into the Vendor Tree + Because of the mergeinfo propagation issues described + earlier, it is very important that you never merge changes + into a sparse working copy. You must always have a full + checkout of the branch you will merge into. For instance, + when merging from HEAD to 7, you must have a full checkout + of stable/7: - This section is an example of importing and tagging - byacc into - head. + &prompt.user; cd stable/7 +&prompt.user; svn up --set-depth=infinity - First, prepare the directory in - vendor: + The target directory must also be up-to-date and must + not contain any uncommitted changes or stray files. + - &prompt.user; svn co --depth immediates $FSVN/vendor -&prompt.user; cd vendor -&prompt.user; svn mkdir byacc -&prompt.user; svn mkdir byacc/dist + + Identifying Revisions - Now, import the sources into the - dist directory. - Once the files are in place, svn add - the new ones, then svn commit and tag - the imported version. To save time and bandwidth, - direct remote committing and tagging is possible: + Identifying revisions to be merged is a must. If the + target already has complete mergeinfo, ask + SVN for a list: - &prompt.user; svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115 - + &prompt.user; cd stable/6/contrib/openpam +&prompt.user; svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam - - Merging to <literal>head</literal> + If the target does not have complete mergeinfo, check + the log for the merge source. + - Due to this being a new file, copy it for the - merge: + + Merging - &prompt.user; svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc + Now, let us start merging! - Working normally on newly imported sources is still - possible. - - - + + The Principles - - Reverting a Commit + Say you would like to merge: - Reverting a commit to a previous version is fairly - easy: + + + revision $R + - &prompt.user; svn merge -r179454:179453 ROADMAP.txt -&prompt.user; svn commit + + in directory $target in stable branch + $B + - Change number syntax, with negative meaning a reverse - change, can also be used: + + from directory $source in head + - &prompt.user; svn merge -c -179454 ROADMAP.txt -&prompt.user; svn commit + + $FSVN is + svn+ssh://repo.freebsd.org/base + + - This can also be done directly in the repository: + Assuming that revisions $P and $Q have + already been merged, and that the current directory is + an up-to-date working copy of stable/$B, the + existing mergeinfo looks like this: - &prompt.user; svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt + &prompt.user; svn propget svn:mergeinfo -R $target +$target - /head/$source:$P,$Q - - It is important to ensure that the mergeinfo - is correct when reverting a file in order to permit - svn mergeinfo --show-revs=eligible to work as - expected. - + Merging is done like so: - Reverting the deletion of a file is slightly different. - Copying the version of the file that predates the deletion - is required. For example, to restore a file that was - deleted in revision N, restore version N-1: + &prompt.user; svn merge -c$R $FSVN/head/$source $target - &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 -&prompt.user; svn commit + Checking the results of this is possible with + svn diff. - or, equally: + The svn:mergeinfo now looks like: - &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base + &prompt.user; svn propget svn:mergeinfo -R $target +$target - head/$source:$P,$Q,$R - Do not simply recreate the file - manually and svn add it—this will - cause history to be lost. - + If the results are not exactly as shown, assistance + may be required before committing as mistakes may have + been made, or there may be something wrong with the + existing mergeinfo, or there may be a bug in + Subversion. + - - Fixing Mistakes + + Practical Example - While we can do surgery in an emergency, do not plan on - having mistakes fixed behind the scenes. Plan on mistakes - remaining in the logs forever. Be sure to check the output - of svn status and svn - diff before committing. + As a practical example, consider the following + scenario. The changes to netmap.4 + in r238987 are to be merged from CURRENT to 9-STABLE. + The file resides in + head/share/man/man4. According + to , this is + also where to do the merge. Note that in this example + all paths are relative to the top of the svn repository. + For more information on the directory layout, see . - Mistakes will happen but, - they can generally be fixed without - disruption. + The first step is to inspect the existing + mergeinfo. - Take a case of adding a file in the wrong location. The - right thing to do is to svn move the file - to the correct location and commit. This causes just a - couple of lines of metadata in the repository journal, and - the logs are all linked up correctly. + &prompt.user; svn propget svn:mergeinfo -R stable/9/share/man/man4 - The wrong thing to do is to delete the file and then - svn add an independent copy in the - correct location. Instead of a couple of lines of text, the - repository journal grows an entire new copy of the file. - This is a waste. - + Take a quick note of how it looks before moving on + to the next step; doing the actual merge: - - Setting up a <application>svnsync</application> - Mirror + &prompt.user; svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4 +--- Merging r238987 into 'stable/9/share/man/man4': +U stable/9/share/man/man4/netmap.4 +--- Recording mergeinfo for merge of r238987 into +'stable/9/share/man/man4': + U stable/9/share/man/man4 - You probably do not want to do this unless there is a - good reason for it. Such reasons might be to support many - multiple local read-only client machines, or if your network - bandwidth is limited. Starting a fresh mirror from empty - would take a very long time. Expect a minimum of 10 hours - for high speed connectivity. If you have international - links, expect this to take 4 to 10 times longer. + Check that the revision number of the merged + revision has been added. Once this is verified, the + only thing left is the actual commit. - A far better option is to grab a seed file. It is large - (~1GB) but will consume less network traffic and take less - time to fetch than a svnsync will. This is possible in one - of the following three ways: + &prompt.user; svn commit stable/9/share/man/man4 + - &prompt.user; rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 . + + Merging into the Kernel + (<filename>sys/</filename>) - &prompt.user; rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz . + As stated above, merging into the kernel is + different from merging in the rest of the tree. In many + ways merging to the kernel is simpler because there is + always the same merge target + (sys/). - &prompt.user; fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz + Once svn merge has been executed, + svn diff has to be run on the + directory to check the changes. This may show some + unrelated property changes, but these can be ignored. + Next, build and test the kernel, and, once the tests are + complete, commit the code as normal, making sure that + the commit message starts with Merge + r226222 from head, + or similar. + + - Once you have the file, extract it to somewhere like - home/svnmirror/base/. - Then, update it, so that it fetches changes since the last - revision in the archive: + + Precautions Before Committing - &prompt.user; svnsync sync file:///home/svnmirror/base + As always, build world (or appropriate parts of + it). - You can then set that up to run from &man.cron.8;, do - checkouts locally, set up a svnserve server for your local - machines to talk to, etc. + Check the changes with svn diff and + svn stat. Make sure all the files that + should have been added or deleted were in fact added or + deleted. - The seed mirror is set to fetch from - svn://svn.freebsd.org/base. The - configuration for the mirror is stored in - revprop 0 on the local mirror. To see - the configuration, try: + Take a closer look at any property change (marked by a + M in the second column of svn + stat). Normally, no svn:mergeinfo properties + should be anywhere except the target directory (or + directories). - &prompt.user; svn proplist -v --revprop -r 0 file:///home/svnmirror/base + If something looks fishy, ask for help. + - Use propset to change things. - + + Committing - - Committing High-<acronym>ASCII</acronym> Data + Make sure to commit a top level directory to have the + mergeinfo included as well. Do not specify individual + files on the command line. For more information about + committing files in general, see the relevant section of + this primer. + + - Files that have high-ASCII bits are - considered binary files in SVN, so the - pre-commit checks fail and indicate that the - mime-type property should be set to - application/octet-stream. However, the - use of this is discouraged, so please do not set it. The - best way is always avoiding high-ASCII - data, so that it can be read everywhere with any text editor - but if it is not avoidable, instead of changing the - mime-type, set the fbsd:notbinary - property with propset: + + Vendor Imports with <acronym>SVN</acronym> - &prompt.user; svn propset fbsd:notbinary yes foo.data - + + Please read this entire section before starting a + vendor import. + - - Maintaining a Project Branch + + Patches to vendor code fall into two + categories: - A project branch is one that is synced to head (or - another branch) is used to develop a project then commit it - back to head. In SVN, - dolphin branching is used for this. A - dolphin branch is one that diverges for a - while and is finally committed back to the original branch. - During development code migration in one direction (from - head to the branch only). No code is committed back to head - until the end. Once you commit back at the end, the branch - is dead (although you can have a new branch with the same - name after you delete the branch if you want). - - As per http://people.freebsd.org/~peter/svn_notes.txt, - work that is intended to be merged back into HEAD should be - in base/projects/. If you are doing - work that is beneficial to the &os; community in some way - but not intended to be merged directly back into HEAD then - the proper location is - base/user/your-name/. - This - page contains further details. - - To create a project branch: - - &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif + + + Vendor patches: these are patches that have been + issued by the vendor, or that have been extracted from + the vendor's version control system, which address + issues which in your opinion cannot wait until the + next vendor release. + - To merge changes from HEAD back into the project - branch: + + &os; patches: these are patches that modify the + vendor code to address &os;-specific issues. + + - &prompt.user; cd copy_of_spif -&prompt.user; svn merge svn+ssh://repo.freebsd.org/base/head -&prompt.user; svn commit + The nature of a patch dictates where it should be + committed: - It is important to resolve any merge conflicts before - committing. - - - + + Preparing the Tree - - Some Tips + If importing for the first time after the switch to + Subversion, flattening and cleaning up the vendor tree is + necessary, as well as bootstrapping the merge history in + the main tree. - In commit logs etc., rev 179872 should be - spelled r179872 as per convention. + + Flattening - Speeding up svn is possible by adding the following to - ~/.ssh/config: + During the conversion from CVS to + Subversion, vendor branches were imported with the same + layout as the main tree. This means that the + pf vendor sources ended up in + vendor/pf/dist/contrib/pf. The + vendor source is best directly in + vendor/pf/dist. - Host * -ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p -ControlMaster auto -ControlPersist yes + To flatten the pf tree: - and then typing + &prompt.user; cd vendor/pf/dist/contrib/pf +&prompt.user; svn mv $(svn list) ../.. +&prompt.user; cd ../.. +&prompt.user; svn rm contrib +&prompt.user; svn propdel -R svn:mergeinfo . +&prompt.user; svn commit - mkdir ~/.ssh/sockets + The propdel bit is necessary + because starting with 1.5, Subversion will automatically + add svn:mergeinfo to any directory + that is copied or moved. In this case, as nothing is + being merged from the deleted tree, they just get in the + way. - Checking out a working copy with a stock Subversion client - without &os;-specific patches - (OPTIONS_SET=FREEBSD_TEMPLATE) will mean - that $FreeBSD$ tags will not - be expanded. Once the correct version has been installed, - trick Subversion into expanding them like so: + Tags may be flattened as well (3, 4, 3.5 etc.); the + procedure is exactly the same, only changing + dist to 3.5 or + similar, and putting the svn commit + off until the end of the process. + - &prompt.user; svn propdel -R svn:keywords . -&prompt.user; svn revert -R . + + Cleaning Up - This will wipe out uncommitted patches. + The dist tree can be cleaned up + as necessary. Disabling keyword expansion is + recommended, as it makes no sense on unmodified vendor + code and in some cases it can even be harmful. + OpenSSH, for example, + includes two files that originated with &os; and still + contain the original version tags. To do this: - It is possible to automatically fill the "Sponsored by" - and "MFC after" commit log fields by setting - "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the - "[miscellany]" section of the - ~/.subversion/config configuration file. - For example: + &prompt.user; svn propdel svn:keywords -R . +&prompt.user; svn commit + - freebsd-sponsored-by = The FreeBSD Foundation -freebsd-mfc-after = 2 weeks - - + + Bootstrapping Merge History - - Setup, Conventions, and Traditions + If importing for the first time after the switch to + Subversion, bootstrap svn:mergeinfo + on the target directory in the main tree to the revision + that corresponds to the last related change to the + vendor tree, prior to importing new sources: - There are a number of things to do as a new developer. - The first set of steps is specific to committers only. These - steps must be done by a mentor for those who are not - committers. + &prompt.user; cd head/contrib/pf +&prompt.user; svn merge --record-only svn+ssh://repo.freebsd.org/base/vendor/pf/dist@180876 . +&prompt.user; svn commit + + - - For New Committers + + Importing New Sources - Those who have been given commit rights to the &os; - repositories must follow these steps. + With two commits—one for the import itself and + one for the tag—this step can optionally be repeated + for every upstream release between the last import and the + current import. - - - Get mentor approval before committing each of these - changes! - + + Preparing the Vendor Sources - - The .ent and - .xml files mentioned below exist in - the &os; Documentation Project SVN repository at svn.FreeBSD.org/doc/. - + Unlike in CVS where only the + needed parts were imported into the vendor tree to avoid + bloating the main tree, Subversion is able to store a + full distribution in the vendor tree. So, import + everything, but merge only what is required. - - New files that do not have the - FreeBSD=%H - svn:keywords property will be rejected - when attempting to commit them to the repository. Be sure - to read - - regarding adding and removing files. Verify that - ~/.subversion/config contains the - necessary auto-props entries from - auto-props.txt mentioned - there. - + A svn add is required to add any + files that were added since the last vendor import, and + svn rm is required to remove any that + were removed since. Preparing sorted lists of the + contents of the vendor tree and of the sources that are + about to be imported is recommended, to facilitate the + process. - - All src commits should go to - &os.current; first before being merged to &os.stable;. - The &os.stable; branch must maintain - ABI and API - compatibility with earlier versions of that branch. Do - not merge changes that break this compatibility. - - + &prompt.user; cd vendor/pf/dist +&prompt.user; svn list -R | grep -v '/$' | sort >../old +&prompt.user; cd ../pf-4.3 +&prompt.user; find . -type f | cut -c 3- | sort >../new - - Steps for New Committers + With these two files, + comm -23 ../old ../new will list + removed files (files only in old), + while comm -13 ../old ../new will + list added files only in + new. + - - Add an Author Entity + + Importing into the Vendor Tree - doc/head/share/xml/authors.ent - — Add an author entity. Later steps depend on this - entity, and missing this step will cause the - doc/ build to fail. This is a - relatively easy task, but remains a good first test of - version control skills. - + Now, the sources must be copied into + dist and + the svn add and + svn rm commands should be used as + needed: - - Update the List of Developers and - Contributors + &prompt.user; cd vendor/pf/pf-4.3 +&prompt.user; tar cf - . | tar xf - -C ../dist +&prompt.user; cd ../dist +&prompt.user; comm -23 ../old ../new | xargs svn rm +&prompt.user; comm -13 ../old ../new | xargs svn --parents add - doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml - — - Add an entry to the Developers section - of the Contributors - List. Entries are sorted by last name. - - doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml - — Remove the entry from the - Additional Contributors section. Entries - are sorted by first name. - + If any directories were removed, they will have to + be svn rmed manually. Nothing will + break if they are not, but they will remain in the + tree. - - Add a News Item + Check properties on any new files. All text files + should have svn:eol-style set to + native. All binary files should have + svn:mime-type set to + application/octet-stream unless there + is a more appropriate media type. Executable files + should have svn:executable set to + *. No other properties should exist + on any file in the tree. - doc/head/share/xml/news.xml - — 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 - core@FreeBSD.org. - + Committing is now possible, however it is good + practice to make sure that everything is OK by using the + svn stat and + svn diff commands. + - - Add a <acronym>PGP</acronym> Key + + Tagging - doc/head/share/pgpkeys/pgpkeys.ent - and - doc/head/share/pgpkeys/pgpkeys-developers.xml - - Add your PGP or - GnuPG key. Those who do not yet have a - key should see . - - &a.des.email; has written a shell script - (doc/head/share/pgpkeys/addkey.sh) to - make this easier. See the README - file for more information. - - Use - doc/head/share/pgpkeys/checkkey.sh to - verify that keys meet minimal best-practices - standards. - - After adding and checking a key, add both updated - files to source control and then commit them. Entries in - this file are sorted by last name. + Once committed, vendor releases should be tagged for + future reference. The best and quickest way to do this + is directly in the repository: - - It is very important to have a current - PGP/GnuPG key in - the repository. The key may be required for positive - identification of a committer. For example, the - &a.admins; might need it for account recovery. A - complete keyring of FreeBSD.org users is - available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. - - + &prompt.user; svn cp svn+ssh://repo.freebsd.org/base/vendor/pf/dist svn+ssh://repo.freebsd.org/base/vendor/pf/4.3 - - Update Mentor and Mentee Information + Once that is complete, svn up the + working copy of + vendor/pf + to get the new tag, although this is rarely + needed. - base/head/share/misc/committers-repository.dot - — Add an entry to the current committers section, - where repository is - doc, ports, or - src, depending on the commit privileges - granted. - - Add an entry for each additional mentor/mentee - relationship in the bottom section. - - - - Generate a <application>Kerberos</application> - Password - - See to generate or - set a Kerberos for use with - other &os; services like the bug tracking database. - - - - Optional: Enable Wiki Account - - &os; - Wiki Account — A wiki account allows - sharing projects and ideas. Those who do not yet have an - account can contact clusteradm@FreeBSD.org - to obtain one. - - - - Optional: Update Wiki Information - - Wiki Information - After gaining access to the wiki, - some people add entries to the How We - Got Here, - Irc - Nicks, and Dogs - of FreeBSD pages. - - - - Optional: Update Ports with Personal - Information - - ports/astro/xearth/files/freebsd.committers.markers - and - 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. - - - - Optional: Prevent Duplicate Mailings - - Subscribers to &a.svn-src-all.name;, - &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish - to unsubscribe to avoid receiving duplicate copies of - commit messages and followups. - - - - - - For Everyone - - - - Introduce yourself to the other developers, otherwise - no one will have any idea who you are or what you are - working on. The introduction need not be a comprehensive - biography, just write a paragraph or two about who you - are, what you plan to be working on as a developer in - &os;, and who will be your mentor. Email this to the - &a.developers; and you will be on your way! - - - - Log into freefall.FreeBSD.org - and create a - /var/forward/user - (where user is your username) - file containing the e-mail address where you want mail - addressed to - yourusername@FreeBSD.org to be - forwarded. This includes all of the commit messages as - well as any other mail addressed to the &a.committers; and - the &a.developers;. Really large mailboxes which have - taken up permanent residence on - freefall may get truncated - without warning if space needs to be freed, so forward it - or read it and you will not lose it. - - Due to the severe load dealing with SPAM places on the - central mail servers that do the mailing list processing - the front-end server does do some basic checks and will - drop some messages based on these checks. At the moment - proper DNS information for the connecting host is the only - check in place but that may change. Some people blame - these checks for bouncing valid email. If you want these - checks turned off for your email you can place a file - named .spam_lover in your home - directory on freefall.FreeBSD.org - to disable the checks for your email. - - - - - Those who are developers but not committers will - not be subscribed to the committers or developers mailing - lists. The subscriptions are derived from the access - rights. - - - - - Mentors - - All new developers have a mentor assigned to them for - the first few months. A mentor is responsible for teaching - the mentee the rules and conventions of the project and - guiding their first steps in the developer community. The - mentor is also personally responsible for the mentee's actions - during this initial period. - - For committers: do not commit anything without first - getting mentor approval. Document that approval with an - Approved by: line in the commit - message. - - When the mentor decides that a mentee has learned the - ropes and is ready to commit on their own, the mentor - announces it with a commit to - conf/mentors. This file is in the - svnadmin branch of each - repository: - - - - - - src - base/svnadmin/conf/mentors - - - - doc - doc/svnadmin/conf/mentors - - - - ports - ports/svnadmin/conf/mentors - - - - - - - - - Commit Log Messages - - This section contains some suggestions and traditions for - how commit logs are formatted. - - As well as including an informative message with each - commit you may need to include some additional - information. - - This information consists of one or more lines - containing the key word or phrase, a colon, tabs for formatting, - and then the additional information. - - The key words or phrases are: - - - - - - PR: - The problem report (if any) which is affected - (typically, by being closed) by this commit. Only - include one PR per line as the automated scripts which - parse this line cannot understand more than - one. - - - - Submitted by: - - The name and e-mail address of the person - that submitted the fix; for developers, just the - username on the &os; cluster. - - If the submitter is the maintainer of the port - to which you are committing, include "(maintainer)" - after the email address. - - Avoid obfuscating the email address of the - submitter as this adds additional work when searching - logs. - - - - - Reviewed by: - The name and e-mail address of the person or - people that reviewed the change; for developers, - just the username on the &os; cluster. If a - patch was submitted to a mailing list for review, - and the review was favorable, then just include - the list name. - - - - Approved by: - The name and e-mail address of the person or - people that approved the change; for developers, just - the username on the &os; cluster. It is customary to - get prior approval for a commit if it is to an area of - the tree to which you do not usually commit. In - addition, during the run up to a new release all commits - must be approved by the release - engineering team. - - While under mentorship, get mentor approval before - the commit. Enter the mentor's username in this field, - and note that they are a mentor: - - Approved by: username-of-mentor (mentor) - - If a team approved these commits then include the - team name followed by the username of the approver in - parentheses. For example: - - Approved by: re (username) - - - - Obtained from: - The name of the project (if any) from which - the code was obtained. Do not use this line for the - name of an individual person. - - - - MFC after: - If you wish to receive an e-mail reminder to - MFC at a later date, specify the - number of days, weeks, or months after which an - MFC is planned. - - - - Relnotes: - If the change is a candidate for inclusion in - the release notes for the next release from the branch, - set to yes. - - - - Security: - If the change is related to a security - vulnerability or security exposure, include one or more - references or a description of the issue. If possible, - include a VuXML URL or a CVE ID. - - - - Differential Revision: - The full URL of the Phabricator review. This line - must be the last line. For example: - https://reviews.freebsd.org/D1708. - - - - - - - Commit Log for a Commit Based on a PR - - You want to commit a change based on a PR submitted by - John Smith containing a patch. The end of the commit message - should look something like this. - - ... - - PR: 12345 - Submitted by: John Smith <John.Smith@example.com> - - - - Commit Log for a Commit Needing Review - - You want to change the virtual memory system. You have - posted patches to the appropriate mailing list (in this - case, freebsd-arch) and the changes have - been approved. - - ... - - Reviewed by: -arch - - - - Commit Log for a Commit Needing Approval - - You want to commit a port. You have collaborated with - the listed MAINTAINER, who has told you to go ahead and - commit. - - ... - - Approved by: abc (maintainer) - - Where abc is the account name - of the person who approved. - - - - Commit Log for a Commit Bringing in Code from - OpenBSD - - You want to commit some code based on work done in the - OpenBSD project. - - ... - - Obtained from: OpenBSD - - - - Commit Log for a Change to &os.current; with a Planned - Commit to &os.stable; to Follow at a Later Date. - - You want to commit some code which will be merged from - &os.current; into the &os.stable; branch after two - weeks. - - ... - -MFC after: 2 weeks - - Where 2 is the number of days, - weeks, or months after which an MFC is - planned. The weeks option may be - day, days, - week, weeks, - month, months. - - - In many cases you may need to combine some of these. - - Consider the situation where a user has submitted a PR - containing code from the NetBSD project. You are looking at the - PR, but it is not an area of the tree you normally work in, so - you have decided to get the change reviewed by the - arch mailing list. Since the change is - complex, you opt to MFC after one month to - allow adequate testing. - - The extra information to include in the commit would look - something like - - - Example Combined Commit Log - - PR: 54321 -Submitted by: John Smith <John.Smith@example.com> -Reviewed by: -arch -Obtained from: NetBSD -MFC after: 1 month -Relnotes: yes - - - - - Preferred License for New Files - - Currently the &os; Project suggests and uses the following - text as the preferred license scheme: - - /*- - * Copyright (c) [year] [your name] - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * [id for your version control system, if any] - */ - - The &os; project strongly discourages the so-called - "advertising clause" in new code. Due to the large number of - contributors to the &os; project, complying with this clause for - many commercial vendors has become difficult. If you have code - in the tree with the advertising clause, please consider - removing it. In fact, please consider using the above license - for your code. - - The &os; project discourages completely new licenses and - variations on the standard licenses. New licenses require the - approval of the &a.core; to reside in the - main 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. For example, the GENERIC kernel - must be compiled under only licenses identical to or - substantially similar to the BSD license. GPL, APSL, CDDL, etc, - licensed software must not be compiled into GENERIC. - - Developers are reminded that in open source, getting "open" - right is just as important as getting "source" right, as - improper handling of intellectual property has serious - consequences. Any questions or concerns should immediately be - brought to the attention of the core team. - - - - Keeping Track of Licenses Granted to the &os; - Project - - Various software or data exist in the repositories where - the &os; project has been granted a special licence to be able - to use them. A case in point are the Terminus fonts for use - with &man.vt.4;. Here the author Dimitar Zhekov has allowed us - to use the "Terminus BSD Console" font under a 2-clause BSD - license rather than the regular Open Font License he normally - uses. - - It is clearly sensible to keep a record of any such - license grants. To that end, the &a.core; has decided to keep - an archive of them. Whenever the &os; project is granted a - special license we require the &a.core; to be notified. Any - developers involved in arranging such a license grant, please - send details to the &a.core; including: - - - - Contact details for people or organizations granting the - special license. - - - - What files, directories etc. in the repositories are - covered by the license grant including the revision numbers - where any specially licensed material was committed. - - - - The date the license comes into effect from. Unless - otherwise agreed, this will be the date the license was - issued by the authors of the software in question. - - - - The license text. - - - - A note of any restrictions, limitations or exceptions - that apply specifically to &os;'s usage of the licensed - material. - - - - Any other relevant information. - - - - Once the &a.core; is satisfied that all the necessary - details have been gathered and are correct, the secretary will - send a PGP-signed acknowledgement of receipt including the - license details. This receipt will be persistently archived and - serve as our permanent record of the license grant. - - The license archive should contain only details of license - grants; this is not the place for any discussions around - licensing or other subjects. Access to data within the license - archive will be available on request to the &a.core;. - + If creating the tag in the working copy of the tree, + svn:mergeinfo results must be + removed: - - Developer Relations + &prompt.user; cd vendor/pf +&prompt.user; svn cp dist 4.3 +&prompt.user; svn propdel svn:mergeinfo -R 4.3 + + - If you are 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. If you see 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. If, however, you are - about to modify something which is clearly being actively - maintained by someone else (and it is only by watching the - repository-committers - mailing list that you can really get a feel for just what is and - is not) then consider sending the change to them instead, just - as you would have before becoming a committer. For ports, you - should contact the listed MAINTAINER in the - Makefile. For other parts of the - repository, if you are unsure who the active maintainer might - be, it may help to 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 - ~eadler/bin/whodid. If your queries go - unanswered or the committer otherwise indicates a lack of - interest in the area affected, go ahead and commit it. + + Merging to Head - - Avoid sending private emails to maintainers. Other people - might be interested in the conversation, not just the final - output. - + &prompt.user; cd head/contrib/pf +&prompt.user; svn up +&prompt.user; svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/vendor/pf/dist . - If you are unsure about a commit for any reason at all, have - it reviewed by -hackers before committing. - Better to have it flamed then and there rather than when it is - part of the repository. If you do happen to commit something - which results in controversy erupting, you may also wish to - consider backing the change out again until the matter is - settled. Remember – with a version control system we can - always change it back. + The --accept=postpone tells + Subversion that it should not complain because merge + conflicts will be taken care of manually. - Do not impugn the intentions of someone you disagree with. - If they see a different solution to a problem than you, or even - a different problem, it is not because they are stupid, because - they have questionable parentage, or because they are trying to - destroy your hard work, personal image, or &os;, but simply - because they have a different outlook on the world. Different - is good. + + The cvs2svn changeover occurred + on June 3, 2008. When performing vendor merges for + packages which were already present and converted by the + cvs2svn process, the command used to + merge + /vendor/package_name/dist + to + /head/package_location + (for example, + head/contrib/sendmail) must use + to + indicate the revision to merge from the + /vendor tree. For example: - Disagree honestly. Argue your position from its merits, - be honest about any shortcomings it may have, and be open to - seeing their solution, or even their vision of the problem, - with an open mind. + &prompt.user; svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/sendmail +&prompt.user; cd sendmail +&prompt.user; svn merge -c r261190 ^/vendor/sendmail/dist . - Accept correction. We are all fallible. When you have made - a mistake, apologize and get on with life. Do not beat up - yourself, and certainly do not beat up others for your mistake. - Do not waste time on embarrassment or recrimination, just fix - the problem and move on. + ^ is an alias for the + repository path. + - Ask for help. Seek out (and give) peer reviews. One of - the ways open source software is supposed to excel is in the - number of eyeballs applied to it; this does not apply if nobody - will review code. - + + If using the Zsh shell, + the ^ must be escaped with + \. This means + ^/head should be + \^/head. + - - If in Doubt... + It is necessary to resolve any merge conflicts. - When you are not sure about something, whether it be a - technical issue or a project convention be sure to ask. If you - stay silent you will never make progress. + Make sure that any files that were added or removed in + the vendor tree have been properly added or removed in the + main tree. To check diffs against the vendor + branch: - If it relates to a technical issue ask on the public - mailing lists. Avoid the temptation to email the individual - person that knows the answer. This way everyone will be able to - learn from the question and the answer. + &prompt.user; svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/vendor/pf/dist --new=. - For project specific or administrative questions you should - ask, in order: + The --no-diff-deleted tells + Subversion not to complain about files that are in the + vendor tree but not in the main tree, i.e., things that + would have previously been removed before the vendor + import, like for example the vendor's makefiles + and configure scripts. - - - Your mentor or former mentor. - + Using CVS, once a file was off the + vendor branch, it was not able to be put back. With + Subversion, there is no concept of on or off the vendor + branch. If a file that previously had local + modifications, to make it not show up in diffs in the + vendor tree, all that has to be done is remove any + left-over cruft like &os; version tags, which is much + easier. - - An experienced committer on IRC, email, etc. - + If any changes are required for the world to build + with the new sources, make them now, and keep testing + until everything builds and runs perfectly. + - - Any team with a "hat", as they should give you a - definitive answer. - + + Committing the Vendor Import - - If still not sure, ask on &a.developers;. - - + Committing is now possible! Everything must be + committed in one go. If done properly, the tree will move + from a consistent state with old code, to a consistent + state with new code. + - Once your question is answered, if no one pointed you to - documentation that spelled out the answer to your question, - document it, as others will have the same question. - + + From Scratch - - Bugzilla + + Importing into the Vendor Tree - The &os; Project utilizes - Bugzilla for tracking bugs and change - requests. Be sure that if you commit a fix or suggestion found - in the PR database to close it. It is also considered nice if - you take time to close any PRs associated with your commits, if - appropriate. + This section is an example of importing and tagging + byacc into + head. - Committers with - non-&os;.org - Bugzilla accounts can have the old account merged with the - &os;.org account by - entering a new bug. Choose - Supporting Services as the Product, and - Bug Tracker as the Component. + First, prepare the directory in + vendor: - You can find out more about - Bugzilla at: + &prompt.user; svn co --depth immediates $FSVN/vendor +&prompt.user; cd vendor +&prompt.user; svn mkdir byacc +&prompt.user; svn mkdir byacc/dist - - - &os; - Problem Report Handling Guidelines - + Now, import the sources into the + dist directory. + Once the files are in place, svn add + the new ones, then svn commit and tag + the imported version. To save time and bandwidth, + direct remote committing and tagging is possible: - - http://www.FreeBSD.org/support.html - - - + &prompt.user; svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115 + - - Phabricator + + Merging to <literal>head</literal> - The &os; Project utilizes Phabricator - for code review requests. See the CodeReview - wiki page for details. + Due to this being a new file, copy it for the + merge: - + &prompt.user; svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc - - Who's Who + Working normally on newly imported sources is still + possible. + + + - Besides the repository meisters, there are other &os; - project members and teams whom you will probably get to know in - your role as a committer. Briefly, and by no means - all-inclusively, these are: + + Reverting a Commit - - - &a.doceng; + Reverting a commit to a previous version is fairly + easy: - - doceng is the group responsible for the documentation - build infrastructure, approving new documentation - committers, and ensuring that the &os; website and - documentation on the FTP site is up to date with respect - to the subversion tree. It is - not a conflict resolution body. - The vast majority of documentation related discussion - takes place on the &a.doc;. More details regarding the - doceng team can be found in its charter. - Committers interested in contributing to the documentation - should familiarize themselves with the Documentation - Project Primer. - - + &prompt.user; svn merge -r179454:179453 ROADMAP.txt +&prompt.user; svn commit - - &a.bde.email; + Change number syntax, with negative meaning a reverse + change, can also be used: - - Bruce is the Style Police-Meister. When you do a - commit that could have been done better, Bruce will be - there to tell you. Be thankful that someone is. Bruce is - also very knowledgeable on the various standards - applicable to &os;. - - + &prompt.user; svn merge -c -179454 ROADMAP.txt +&prompt.user; svn commit - - &a.re.members.email; + This can also be done directly in the repository: - - These are the members of the &a.re;. This team is - responsible for setting release deadlines and controlling - the release process. During code freezes, the release - engineers have final authority on all changes to the - system for whichever branch is pending release status. If - there is something you want merged from &os.current; to - &os.stable; (whatever values those may have at any given - time), these are the people to talk to about it. - - Hiroki is also the keeper of the release documentation - (src/release/doc/*). If you commit a - change that you think is worthy of mention in the release - notes, please make sure he knows about it. Better still, - send him a patch with your suggested commentary. - - + &prompt.user; svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt - - &a.so.email; + + It is important to ensure that the mergeinfo + is correct when reverting a file in order to permit + svn mergeinfo --show-revs=eligible to work as + expected. + - - &a.so; is the - &os; Security - Officer and oversees the - &a.security-officer;. - - + Reverting the deletion of a file is slightly different. + Copying the version of the file that predates the deletion + is required. For example, to restore a file that was + deleted in revision N, restore version N-1: - - &a.wollman.email; + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 +&prompt.user; svn commit - - If you need advice on obscure network internals or - are not sure of some potential change to the networking - subsystem you have in mind, Garrett is someone to talk - to. Garrett is also very knowledgeable on the various - standards applicable to &os;. - - + or, equally: - - &a.committers; + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base - - &a.svn-src-all.name;, &a.svn-ports-all.name; and - &a.svn-doc-all.name; are the mailing lists that the - version control system uses to send commit messages to. - You should never send email directly - to these lists. You should only send replies to this list - when they are short and are directly related to a - commit. - - + Do not simply recreate the file + manually and svn add it—this will + cause history to be lost. + - - &a.developers; + + Fixing Mistakes - - All committers are subscribed to -developers. This - list was created to be a forum for the committers - community issues. Examples are Core - voting, announcements, etc. - - The &a.developers; is for the exclusive use of &os; - committers. In order to develop &os;, committers must - have the ability to openly discuss matters that will be - resolved before they are publicly announced. Frank - discussions of work in progress are not suitable for open - publication and may harm &os;. - - All &os; committers are expected not to - not publish or forward messages from the - &a.developers; outside the list membership without - permission of all of the authors. Violators will be - removed from the - &a.developers;, resulting in a suspension of commit - privileges. Repeated or flagrant violations may result in - permanent revocation of commit privileges. - - This list is not intended as a - place for code reviews or for any technical discussion. - In fact using it as such hurts the &os; Project as it - gives a sense of a closed list where general decisions - affecting all of the &os; using community are made without - being open. Last, but not least - never, never ever, email the &a.developers; and - CC:/BCC: another &os; list. Never, ever email - another &os; email list and CC:/BCC: the &a.developers;. - Doing so can greatly diminish the benefits of this - list. - - - - + While we can do surgery in an emergency, do not plan on + having mistakes fixed behind the scenes. Plan on mistakes + remaining in the logs forever. Be sure to check the output + of svn status and svn + diff before committing. - - SSH Quick-Start Guide + Mistakes will happen but, + they can generally be fixed without + disruption. - - - If you do not wish to type your password in every time - you use &man.ssh.1;, and you use keys to - authenticate, &man.ssh-agent.1; is there for your - convenience. If you want to use &man.ssh-agent.1;, make - sure that you run it before running other applications. X - users, for example, usually do this from their - .xsession or - .xinitrc. See &man.ssh-agent.1; for - details. - + Take a case of adding a file in the wrong location. The + right thing to do is to svn move the file + to the correct location and commit. This causes just a + couple of lines of metadata in the repository journal, and + the logs are all linked up correctly. - - Generate a key pair using &man.ssh-keygen.1;. The key - pair will wind up in your - $HOME/.ssh/ - directory. + The wrong thing to do is to delete the file and then + svn add an independent copy in the + correct location. Instead of a couple of lines of text, the + repository journal grows an entire new copy of the file. + This is a waste. + - - Only ECDSA, - Ed25519 or RSA keys - are supported. - - + + Setting up a <application>svnsync</application> + Mirror - - Send your public key - ($HOME/.ssh/id_ecdsa.pub, - $HOME/.ssh/id_ed25519.pub, or - $HOME/.ssh/id_rsa.pub) - to the person setting you up as a committer so it can be put - into - yourlogin - in - /etc/ssh-keys/ on - freefall. - - + You probably do not want to do this unless there is a + good reason for it. Such reasons might be to support many + multiple local read-only client machines, or if your network + bandwidth is limited. Starting a fresh mirror from empty + would take a very long time. Expect a minimum of 10 hours + for high speed connectivity. If you have international + links, expect this to take 4 to 10 times longer. - Now you should be able to use &man.ssh-add.1; for - authentication once per session. This will prompt you for - your private key's pass phrase, and then store it in your - authentication agent (&man.ssh-agent.1;). If you no longer - wish to have your key stored in the agent, issuing - ssh-add -d will remove it. + A far better option is to grab a seed file. It is large + (~1GB) but will consume less network traffic and take less + time to fetch than a svnsync will. This is possible in one + of the following three ways: - Test by doing something such as ssh - freefall.FreeBSD.org ls /usr. + &prompt.user; rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 . - For more information, see - security/openssh, - &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, - &man.ssh-keygen.1;, and &man.scp.1;. + &prompt.user; rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz . - For information on adding, changing, or removing &man.ssh.1; - keys, see this - article. - + &prompt.user; fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz - - &coverity; Availability for &os; Committers + Once you have the file, extract it to somewhere like + home/svnmirror/base/. + Then, update it, so that it fetches changes since the last + revision in the archive: - All &os; developers can obtain access to - Coverity analysis results of all &os; - Project software. All who are interested in obtaining access to - the analysis results of the automated - Coverity runs, can sign up at Coverity - Scan. + &prompt.user; svnsync sync file:///home/svnmirror/base - The &os; wiki includes a mini-guide for developers who are - interested in working with the &coverity; analysis reports: http://wiki.freebsd.org/CoverityPrevent. - Please note that this mini-guide is only readable by &os; - developers, so if you cannot access this page, you will have to - ask someone to add you to the appropriate Wiki access - list. + You can then set that up to run from &man.cron.8;, do + checkouts locally, set up a svnserve server for your local + machines to talk to, etc. - Finally, all &os; developers who are going to use - &coverity; are always encouraged to ask for more details and - usage information, by posting any questions to the mailing list - of the &os; developers. - + The seed mirror is set to fetch from + svn://svn.freebsd.org/base. The + configuration for the mirror is stored in + revprop 0 on the local mirror. To see + the configuration, try: - - The &os; Committers' Big List of Rules + &prompt.user; svn proplist -v --revprop -r 0 file:///home/svnmirror/base - Everyone involved with the &os; project is expected to - abide by the Code of Conduct available from - http://www.FreeBSD.org/internal/code-of-conduct.html. - As committers, you form the public face of the project, and how - you behave has a vital impact on the public perception of it. - This guide expands on the parts of the - Code of Conduct specific to - committers. + Use propset to change things. + - - - Respect other committers. - + + Committing High-<acronym>ASCII</acronym> Data - - Respect other contributors. - + Files that have high-ASCII bits are + considered binary files in SVN, so the + pre-commit checks fail and indicate that the + mime-type property should be set to + application/octet-stream. However, the + use of this is discouraged, so please do not set it. The + best way is always avoiding high-ASCII + data, so that it can be read everywhere with any text editor + but if it is not avoidable, instead of changing the + mime-type, set the fbsd:notbinary + property with propset: - - Discuss any significant change - before committing. - + &prompt.user; svn propset fbsd:notbinary yes foo.data + - - Respect existing maintainers (if listed in the - MAINTAINER field in - Makefile or in - MAINTAINER in the top-level - directory). - + + Maintaining a Project Branch - - Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may override a maintainer's wishes - at the Security Officer's discretion. - + A project branch is one that is synced to head (or + another branch) is used to develop a project then commit it + back to head. In SVN, + dolphin branching is used for this. A + dolphin branch is one that diverges for a + while and is finally committed back to the original branch. + During development code migration in one direction (from + head to the branch only). No code is committed back to head + until the end. Once you commit back at the end, the branch + is dead (although you can have a new branch with the same + name after you delete the branch if you want). - - Changes go to &os.current; before &os.stable; unless - specifically permitted by the release engineer or unless - they are not applicable to &os.current;. Any non-trivial or - non-urgent change which is applicable should also be allowed - to sit in &os.current; for at least 3 days before merging so - that it can be given sufficient testing. The release - engineer has the same authority over the &os.stable; branch - as outlined for the maintainer in rule #5. - + As per http://people.freebsd.org/~peter/svn_notes.txt, + work that is intended to be merged back into HEAD should be + in base/projects/. If you are doing + work that is beneficial to the &os; community in some way + but not intended to be merged directly back into HEAD then + the proper location is + base/user/your-name/. + This + page contains further details. - - Do not fight in public with other committers; it looks - bad. - + To create a project branch: - - Respect all code freezes and read the - committers and - developers mailing lists in a timely - manner so you know when a code freeze is in effect. - + &prompt.user; svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif - - When in doubt on any procedure, ask first! - + To merge changes from HEAD back into the project + branch: - - Test your changes before committing them. - + &prompt.user; cd copy_of_spif +&prompt.user; svn merge svn+ssh://repo.freebsd.org/base/head +&prompt.user; svn commit - - Do not commit to anything under the - src/contrib, - src/crypto, or - src/sys/contrib trees without - explicit approval from the respective - maintainer(s). - - + It is important to resolve any merge conflicts before + committing. + + + - Details + Some Tips - - - Respect other committers. + In commit logs etc., rev 179872 should be + spelled r179872 as per convention. - This means that you need to treat other committers as - the peer-group developers that they are. Despite our - occasional attempts to prove the contrary, one does not - get to be a committer by being stupid and nothing rankles - more than being treated that way by one of your peers. - Whether we always feel respect for one another or not (and - everyone has off days), we still have to - treat other committers with respect - at all times, on public forums and in private - email. - - Being able to work together long term is this - project's greatest asset, one far more important than any - set of changes to the code, and turning arguments about - code into issues that affect our long-term ability to work - harmoniously together is just not worth the trade-off by - any conceivable stretch of the imagination. - - To comply with this rule, do not send email when you - are angry or otherwise behave in a manner which is likely - to strike others as needlessly confrontational. First - calm down, then think about how to communicate in the most - effective fashion for convincing the other person(s) that - your side of the argument is correct, do not just blow off - some steam so you can feel better in the short term at the - cost of a long-term flame war. Not only is this very bad - energy economics, but repeated displays of - public aggression which impair our ability to work well - together will be dealt with severely by the project - leadership and may result in suspension or termination of - your commit privileges. The project leadership will take - into account both public and private communications - brought before it. It will not seek the disclosure of - private communications, but it will take it into account - if it is volunteered by the committers involved in the - complaint. - - All of this is never an option which the project's - leadership enjoys in the slightest, but unity comes first. - No amount of code or good advice is worth trading that - away. - + Speeding up svn is possible by adding the following to + ~/.ssh/config: - - Respect other contributors. + Host * +ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p +ControlMaster auto +ControlPersist yes - You were not always a committer. At one time you were - a contributor. Remember that at all times. Remember what - it was like trying to get help and attention. Do not - forget that your work as a contributor was very important - to you. Remember what it was like. Do not discourage, - belittle, or demean contributors. Treat them with - respect. They are our committers in waiting. They are - every bit as important to the project as committers. - Their contributions are as valid and as important as your - own. After all, you made many contributions before you - became a committer. Always remember that. - - Consider the points raised under - and apply them also to - contributors. - + and then typing - - Discuss any significant change - before committing. + mkdir ~/.ssh/sockets + + Checking out a working copy with a stock Subversion client + without &os;-specific patches + (OPTIONS_SET=FREEBSD_TEMPLATE) will mean + that $FreeBSD$ tags will not + be expanded. Once the correct version has been installed, + trick Subversion into expanding them like so: + + &prompt.user; svn propdel -R svn:keywords . +&prompt.user; svn revert -R . + + This will wipe out uncommitted patches. - The repository is not where changes should be - initially submitted for correctness or argued over, that - should happen first in the mailing lists or by use of the - Phabricator service and the commit should only happen once - something resembling consensus has been reached. This - does not mean that you have to ask permission before - correcting every obvious syntax error or manual page - misspelling, simply that you should try to develop a feel - for when a proposed change is not quite such a no-brainer - and requires some feedback first. People really do not - mind sweeping changes if the result is something clearly - better than what they had before, they just do not like - being surprised by those changes. - The very best way of making sure that you are on the right - track is to have your code reviewed by one or more other - committers. + It is possible to automatically fill the "Sponsored by" + and "MFC after" commit log fields by setting + "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the + "[miscellany]" section of the + ~/.subversion/config configuration file. + For example: - When in doubt, ask for review! - + freebsd-sponsored-by = The FreeBSD Foundation +freebsd-mfc-after = 2 weeks + + - - Respect existing maintainers if listed. + + Commit Log Messages - Many parts of &os; are not owned in - the sense that any specific individual will jump up and - yell if you commit a change to their area, - but it still pays to check first. One convention we use - is to put a maintainer line in the - Makefile for any package or subtree - which is being actively maintained by one or more people; - see http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html - for documentation on this. Where sections of code have - several maintainers, commits to affected areas by one - maintainer need to be reviewed by at least one other - maintainer. In cases where the - maintainer-ship of something is not clear, - you can also look at the repository logs for the file(s) - in question and see if someone has been working recently - or predominantly in that area. - - Other areas of &os; fall under the control of someone - who manages an overall category of &os; evolution, such as - internationalization or networking. See http://www.FreeBSD.org/administration.html - for more information on this. - + This section contains some suggestions and traditions for + how commit logs are formatted. - - Any disputed change must be backed out pending - resolution of the dispute if requested by a maintainer. - Security related changes may override a maintainer's - wishes at the Security Officer's discretion. - - This may be hard to swallow in times of conflict (when - each side is convinced that they are in the right, of - course) but a version control system makes it unnecessary - to have an ongoing dispute raging when it is far easier to - simply reverse the disputed change, get everyone calmed - down again and then try to figure out what is the best way - to proceed. If the change turns out to be the best thing - after all, it can be easily brought back. If it turns out - not to be, then the users did not have to live with the - bogus change in the tree while everyone was busily - debating its merits. People very - rarely call for back-outs in the repository since - discussion generally exposes bad or controversial changes - before the commit even happens, but on such rare occasions - the back-out should be done without argument so that we - can get immediately on to the topic of figuring out - whether it was bogus or not. - + As well as including an informative message with each + commit you may need to include some additional + information. - - Changes go to &os.current; before &os.stable; unless - specifically permitted by the release engineer or unless - they are not applicable to &os.current;. Any non-trivial - or non-urgent change which is applicable should also be - allowed to sit in &os.current; for at least 3 days before - merging so that it can be given sufficient testing. The - release engineer has the same authority over the - &os.stable; branch as outlined in rule #5. - - This is another do not argue about it - issue since it is the release engineer who is ultimately - responsible (and gets beaten up) if a change turns out to - be bad. Please respect this and give the release engineer - your full cooperation when it comes to the &os.stable; - branch. The management of &os.stable; may frequently seem - to be overly conservative to the casual observer, but also - bear in mind the fact that conservatism is supposed to be - the hallmark of &os.stable; and different rules apply - there than in &os.current;. There is also really no point - in having &os.current; be a testing ground if changes are - merged over to &os.stable; immediately. Changes need a - chance to be tested by the &os.current; developers, so - allow some time to elapse before merging unless the - &os.stable; fix is critical, time sensitive or so obvious - as to make further testing unnecessary (spelling fixes to - manual pages, obvious bug/typo fixes, etc.) In other - words, apply common sense. - - Changes to the security branches (for example, - releng/9.3) must be approved by a - member of the &a.security-officer;, or in some cases, by a - member of the &a.re;. - + This information consists of one or more lines + containing the key word or phrase, a colon, tabs for formatting, + and then the additional information. - - Do not fight in public with other committers; it looks - bad. + The key words or phrases are: - This project has a public image to uphold and that - image is very important to all of us, especially if we are - to continue to attract new members. There will be - occasions when, despite everyone's very best attempts at - self-control, tempers are lost and angry words are - exchanged. The best thing that can be done in such cases - is to minimize the effects of this until everyone has - cooled back down. That means that you should not air your - angry words in public and you should not forward private - correspondence or other private communications to public - mailing lists, mail aliases, instant messaging channels or - social media sites. What people say one-to-one is often - much less sugar-coated than what they would say in public, - and such communications therefore have no place there - - they only serve to inflame an already bad situation. If - the person sending you a flame-o-gram at least had the - grace to send it privately, then have the grace to keep it - private yourself. If you feel you are being unfairly - treated by another developer, and it is causing you - anguish, bring the matter up with core rather than taking - it public. Core will do its best to play peace makers and - get things back to sanity. In cases where the dispute - involves a change to the codebase and the participants do - not appear to be reaching an amicable agreement, core may - appoint a mutually-agreeable third party to resolve the - dispute. All parties involved must then agree to be bound - by the decision reached by this third party. - + + + + + PR: + The problem report (if any) which is affected + (typically, by being closed) by this commit. Only + include one PR per line as the automated scripts which + parse this line cannot understand more than + one. + - - Respect all code freezes and read the - committers and - developers mailing list on a timely - basis so you know when a code freeze is in effect. - - Committing unapproved changes during a code freeze is - a really big mistake and committers are expected to keep - up-to-date on what is going on before jumping in after a - long absence and committing 10 megabytes worth of - accumulated stuff. People who abuse this on a regular - basis will have their commit privileges suspended until - they get back from the &os; Happy Reeducation Camp we - run in Greenland. - + + Submitted by: + + The name and e-mail address of the person + that submitted the fix; for developers, just the + username on the &os; cluster. - - When in doubt on any procedure, ask first! + If the submitter is the maintainer of the port + to which you are committing, include "(maintainer)" + after the email address. - Many mistakes are made because someone is in a hurry - and just assumes they know the right way of doing - something. If you have not done it before, chances are - good that you do not actually know the way we do things - and really need to ask first or you are going to - completely embarrass yourself in public. 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. - + Avoid obfuscating the email address of the + submitter as this adds additional work when searching + logs. + + - - Test your changes before committing them. + + Reviewed by: + The name and e-mail address of the person or + people that reviewed the change; for developers, + just the username on the &os; cluster. If a + patch was submitted to a mailing list for review, + and the review was favorable, then just include + the list name. + - - 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 refer to the - &os; - Internal Page for a list of available resources. - As other architectures are added to the &os; supported - platforms list, the appropriate shared testing resources - will be made available. - + + Approved by: + The name and e-mail address of the person or + people that approved the change; for developers, just + the username on the &os; cluster. It is customary to + get prior approval for a commit if it is to an area of + the tree to which you do not usually commit. In + addition, during the run up to a new release all commits + must be approved by the release + engineering team. - - Do not commit to anything under the - src/contrib, - src/crypto, and - src/sys/contrib trees without - explicit approval from the respective - maintainer(s). - - The trees mentioned above are for contributed software - usually imported onto a vendor branch. Committing - something there, even if it does not take the file off the - vendor branch, may cause unnecessary headaches for those - responsible for maintaining that particular piece of - software. Thus, unless you have - explicit approval from the maintainer - (or you are the maintainer), do not - commit there! - - Please note that this does not mean you should not try - to improve the software in question; you are still more - than welcome to do so. Ideally, you should submit your - patches to the vendor. If your changes are - &os;-specific, talk to the maintainer; they may be - willing to apply them locally. But whatever you do, do - not commit there by yourself! + While under mentorship, get mentor approval before + the commit. Enter the mentor's username in this field, + and note that they are a mentor: - Contact the &a.core; if you wish to take up - maintainership of an unmaintained part of the tree. - - - + Approved by: username-of-mentor (mentor) - - Policy on Multiple Architectures + If a team approved these commits then include the + team name followed by the username of the approver in + parentheses. For example: - &os; has added several new architecture ports during - recent release cycles and is truly no longer an &i386; centric - operating system. In an effort to make it easier to keep - &os; portable across the platforms we support, core has - developed the following mandate: + Approved by: re (username) + -
- Our 32-bit reference platform is &arch.i386;, and our - 64-bit reference platform is &arch.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. -
+ + Obtained from: + The name of the project (if any) from which + the code was obtained. Do not use this line for the + name of an individual person. + - The &arch.i386; and &arch.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. + + MFC after: + If you wish to receive an e-mail reminder to + MFC at a later date, specify the + number of days, weeks, or months after which an + MFC is planned. + - We will continue to re-evaluate this policy as cost and - availability of the 64-bit platforms change. + + Relnotes: + If the change is a candidate for inclusion in + the release notes for the next release from the branch, + set to yes. + - 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. - + + Security: + If the change is related to a security + vulnerability or security exposure, include one or more + references or a description of the issue. If possible, + include a VuXML URL or a CVE ID. + - - Other Suggestions + + Differential Revision: + The full URL of the Phabricator review. This line + must be the last line. For example: + http://reviews.freebsd.org/D1708. + + + + - When committing documentation changes, use a spell checker - before committing. For all XML docs, verify that the - formatting directives are correct by running - make lint and - textproc/igor. + + Commit Log for a Commit Based on a PR - For manual pages, run sysutils/manck - and textproc/igor - over the manual page to verify all of the cross - references and file references are correct and that the man - page has all of the appropriate MLINKs - installed. + You want to commit a change based on a PR submitted by + John Smith containing a patch. The end of the commit message + should look something like this. - Do not mix style fixes with new functionality. A style - fix is any change which does not modify the functionality of - the code. Mixing the changes obfuscates the functionality - change when asking for differences between revisions, which - can hide any new bugs. Do not include whitespace changes with - content changes in commits to doc/ . - The extra clutter in the diffs - makes the translators' job much more difficult. Instead, make - any style or whitespace changes in separate commits that are - clearly labeled as such in the commit message. - + ... - - Deprecating Features + PR: 12345 + Submitted by: John Smith <John.Smith@example.com> + - When it is necessary to remove functionality from software - in the base system the following guidelines should be followed - whenever possible: + + Commit Log for a Commit Needing Review - - - Mention is made in the manual page and possibly the - release notes that the option, utility, or interface is - deprecated. Use of the deprecated feature generates a - warning. - + You want to change the virtual memory system. You have + posted patches to the appropriate mailing list (in this + case, freebsd-arch) and the changes have + been approved. - - The option, utility, or interface is preserved until - the next major (point zero) release. - + ... - - The option, utility, or interface is removed and no - longer documented. It is now obsolete. It is also - generally a good idea to note its removal in the release - notes. - - - + Reviewed by: -arch + - - Privacy and Confidentiality + + Commit Log for a Commit Needing Approval - - - Most &os; business is done in public. + You want to commit a port. You have collaborated with + the listed MAINTAINER, who has told you to go ahead and + commit. - &os; is an open project. Which - means that not only can anyone use the source code, but - that most of the development process is open to public - scrutiny. - + ... - - Certain sensitive matters must remain private or - held under embargo. + Approved by: abc (maintainer) - There unfortunately cannot be complete transparency. - As a &os; developer you will have a certain degree of - privileged access to information. Consequently you are - expected to respect certain requirements for - confidentiality. Sometimes the need for confidentiality - comes from external collaborators or has a specific time - limit. Mostly though, it is a matter of not releasing - private communications. - + Where abc is the account name + of the person who approved. + - - The Security Officer has sole control over the - release of security advisories. + + Commit Log for a Commit Bringing in Code from + OpenBSD - Where there are security problems that affect many - different operating systems, &os; frequently depends on - early access in order to be able to prepare advisories for - coordinated release. Unless &os; developers can be - trusted to maintain security, such early access will not - be made available. The Security Officer is responsible - for controlling pre-release access to information about - vulnerabilities, and for timing the release of all - advisories. He may request help under condition of - confidentiality from any developer with relevant knowledge - in order to prepare security fixes. - + You want to commit some code based on work done in the + OpenBSD project. - - Communications with Core are kept confidential for as - long as necessary. + ... - Communications to core will initially be treated as - confidential. Eventually however, most of Core's business - will be summarized into the monthly or quarterly core - reports. Care will be taken to avoid publicising any - sensitive details. Records of some particularly sensitive - subjects may not be reported on at all and will be - retained only in Core's private archives. - + Obtained from: OpenBSD + - - Non-disclosure Agreements may be required for access - to certain commercially sensitive data. + + Commit Log for a Change to &os.current; with a Planned + Commit to &os.stable; to Follow at a Later Date. - Access to certain commercially sensitive data may - only be available under a Non-Disclosure Agreement. The - FreeBSD Foundation legal staff must be consulted before - any binding agreements are entered into. - + You want to commit some code which will be merged from + &os.current; into the &os.stable; branch after two + weeks. - - Private communications should not be made - public without permission. + ... - Beyond the specific requirements above there is a - general expectation not to publish private communications - between developers without the consent of all parties - involved. Ask permission before forwarding a message onto - a public mailing list, or posting it to a forum or website - that can be accessed by other than the original - correspondents. - +MFC after: 2 weeks - - Communications on project-only or restricted access - channels should be treated as private. + Where 2 is the number of days, + weeks, or months after which an MFC is + planned. The weeks option may be + day, days, + week, weeks, + month, months. + - Similarly to personal communications, certain - internal communications channels, including &os; Committer - only mailing lists and restricted access IRC channels - should be considered as private communications. You need - permission in order to publish material from these - sources. - + In many cases you may need to combine some of these. - - Core may approve publication. + Consider the situation where a user has submitted a PR + containing code from the NetBSD project. You are looking at the + PR, but it is not an area of the tree you normally work in, so + you have decided to get the change reviewed by the + arch mailing list. Since the change is + complex, you opt to MFC after one month to + allow adequate testing. - Where it is impractical to obtain permission due to - the number of correspondents or where permission to - publish is unreasonably withheld, Core may approve release - of such private matters that merit more general - publication. - - - - + The extra information to include in the commit would look + something like - - Support for Multiple Architectures + + Example Combined Commit Log - &os; is a highly portable operating system intended to - function on many different types of hardware architectures. - Maintaining clean separation of Machine Dependent (MD) and - Machine Independent (MI) code, as well as minimizing MD code, is - an important part of our strategy to remain agile with regards - to current hardware trends. Each new hardware architecture - supported by &os; adds substantially to the cost of code - maintenance, toolchain support, and release engineering. It - also dramatically increases the cost of effective testing of - kernel changes. As such, there is strong motivation to - differentiate between classes of support for various - architectures while remaining strong in a few key architectures - that are seen as the &os; target audience. + PR: 54321 +Submitted by: John Smith <John.Smith@example.com> +Reviewed by: -arch +Obtained from: NetBSD +MFC after: 1 month +Relnotes: yes + + - - Statement of General Intent + + Preferred License for New Files - The &os; Project targets "production quality commercial - off-the-shelf (COTS) workstation, server, and high-end - embedded systems". By retaining a focus on a narrow set of - architectures of interest in these environments, the &os; - Project is able to maintain high levels of quality, stability, - and performance, as well as minimize the load on various - support teams on the project, such as the ports team, - documentation team, security officer, and release engineering - teams. Diversity in hardware support broadens the options for - &os; consumers by offering new features and usage - opportunities (such as support for 64-bit CPUs, use in - embedded environments, etc.), but these benefits must always - be carefully considered in terms of the real-world maintenance - cost associated with additional platform support. + Currently the &os; Project suggests and uses the following + text as the preferred license scheme: - The &os; Project differentiates platform targets into - four tiers. Each tier includes a specification of the - requirements for an architecture to be in that tier, - as well as specifying the obligations of developers with - regards to the platform. In addition, a policy is defined - regarding the circumstances required to change the tier - of an architecture. - + /*- + * Copyright (c) [year] [your name] + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * + * [id for your version control system, if any] + */ - - Tier 1: Fully Supported Architectures + The &os; project strongly discourages the so-called + "advertising clause" in new code. Due to the large number of + contributors to the &os; project, complying with this clause for + many commercial vendors has become difficult. If you have code + in the tree with the advertising clause, please consider + removing it. In fact, please consider using the above license + for your code. - Tier 1 platforms are fully supported by the security - officer, release engineering, and toolchain maintenance staff. - New features added to the operating system must be fully - functional across all Tier 1 architectures for every release - (features which are inherently architecture-specific, such as - support for hardware device drivers, may be exempt from this - requirement). In general, all Tier 1 platforms must have - build and Tinderbox support either in the FreeBSD.org cluster, - or be easily available for all developers. Embedded platforms - may substitute an emulator available in the &os; cluster - for actual hardware. + The &os; project discourages completely new licenses and + variations on the standard licenses. New licenses require the + approval of the &a.core; to reside in the + main 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. - Tier 1 architectures are expected to be Production Quality - with respects to all aspects of the &os; operating system, - including installation and development environments. + 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. For example, the GENERIC kernel + must be compiled under only licenses identical to or + substantially similar to the BSD license. GPL, APSL, CDDL, etc, + licensed software must not be compiled into GENERIC. - Tier 1 architectures are expected to be completely - integrated into the source tree and have all features - necessary to produce an entire system relevant for that target - architecture. Tier 1 architectures generally have at least 6 - active developers. + Developers are reminded that in open source, getting "open" + right is just as important as getting "source" right, as + improper handling of intellectual property has serious + consequences. Any questions or concerns should immediately be + brought to the attention of the core team. + - Tier 1 architectures are expected to be fully supported by - the ports system. All the ports should build on a Tier 1 - platform, or have the appropriate filters to prevent the - inappropriate ones from building there. The packaging system - must support all Tier 1 architectures. To ensure an - architecture's Tier 1 status, proponents of that architecture - must show that all relevant packages can be built on that - platform. + + Keeping Track of Licenses Granted to the &os; + Project - Tier 1 embedded architectures must be able to cross-build - packages on at least one other Tier 1 architecture. The - packages must be the most relevant for the platform, but may - be a non-empty subset of those that build natively. + Various software or data exist in the repositories where + the &os; project has been granted a special licence to be able + to use them. A case in point are the Terminus fonts for use + with &man.vt.4;. Here the author Dimitar Zhekov has allowed us + to use the "Terminus BSD Console" font under a 2-clause BSD + license rather than the regular Open Font License he normally + uses. - Tier 1 architectures must be fully documented. All basic - operations need to be covered by the handbook or other - documents. All relevant integration documentation must also - be integrated into the tree, or readily available. + It is clearly sensible to keep a record of any such + license grants. To that end, the &a.core; has decided to keep + an archive of them. Whenever the &os; project is granted a + special license we require the &a.core; to be notified. Any + developers involved in arranging such a license grant, please + send details to the &a.core; including: - Current Tier 1 platforms are &arch.i386; and - &arch.amd64;. - + + + Contact details for people or organizations granting the + special license. + - - Tier 2: Developmental Architectures + + What files, directories etc. in the repositories are + covered by the license grant including the revision numbers + where any specially licensed material was committed. + - Tier 2 platforms are not supported by the security officer - and release engineering teams. Platform maintainers are - responsible for toolchain support in the tree. The toolchain - maintainers are expected to work with the platform maintainers - to refine these changes. Major new toolchain components are - allowed to break support for Tier 2 architectures if the - &os;-local changes have not been incorporated upstream. - The toolchain maintainers are expected to provide prompt - review of any proposed changes and cannot block, through their - inaction, changes going into the tree. New features added to - &os; should be feasible to implement on these platforms, - but an implementation is not required before the feature may - be added to the &os; source tree. New features that may be - difficult to implement on Tier 2 architectures should provide - a means of disabling them on those architectures. The - implementation of a Tier 2 architecture may be committed to - the main &os; tree as long as it does not interfere with - production work on Tier 1 platforms, or substantially with - other Tier 2 platforms. Before a Tier 2 platform can be added - to the &os; base source tree, the platform must be able to - boot multi-user on actual hardware. Generally, there must be - at least three active developers working on the - platform. + + The date the license comes into effect from. Unless + otherwise agreed, this will be the date the license was + issued by the authors of the software in question. + - Tier 2 architectures are usually systems targeted at Tier - 1 support, but that are still under development. - Architectures reaching end of life may also be moved from Tier - 1 status to Tier 2 status as the availability of resources to - continue to maintain the system in a Production Quality state - diminishes. Well supported niche architectures may also be - Tier 2. + + The license text. + - Tier 2 architectures have basic support for them - integrated into the ports infrastructure. They may have cross - compilation support added, at the discretion of portmgr. Some - ports must built natively into packages if the package system - supports that architecture. If not integrated into the base - system, some external patches for the architecture for ports - must be available. + + A note of any restrictions, limitations or exceptions + that apply specifically to &os;'s usage of the licensed + material. + - Tier 2 architectures can be integrated into the &os; - handbook. The basics for how to get a system running must be - documented, although not necessarily for every single board or - system a Tier 2 architecture supports. The supported hardware - list must exist and should be relatively recent. It should be - integrated into the &os; documentation. + + Any other relevant information. + + - Current Tier 2 platforms are &arch.arm;, &arch.arm64;, - &arch.ia64; (through &os; 10), - &arch.pc98;, &arch.powerpc;, and &arch.sparc64;. - + Once the &a.core; is satisfied that all the necessary + details have been gathered and are correct, the secretary will + send a PGP-signed acknowledgement of receipt including the + license details. This receipt will be persistently archived and + serve as our permanent record of the license grant. - - Tier 3: Experimental Architectures + The license archive should contain only details of license + grants; this is not the place for any discussions around + licensing or other subjects. Access to data within the license + archive will be available on request to the &a.core;. + - Tier 3 platforms are not supported by the security officer - and release engineering teams. At the discretion of the - toolchain maintainers, they may be supported in the toolchain. - Tier 3 platforms are architectures in the early stages of - development, for non-mainstream hardware platforms, or which - are considered legacy systems unlikely to see broad future - use. Initial support for Tier 3 platforms should be worked on - in external SCM repositories. - The transition to &os;'s subversion should take place after - the platform boots multi-user on hardware; sharing via - subversion is needed for wider exposure; and multiple - developers are actively working on the platform. - Platforms that transition to Tier 3 status may be - removed from the tree if they are no longer actively supported - by the &os; developer community at the discretion of the - release engineer. + + Bugzilla - Tier 3 platforms may have ports support, either integrated - or external, but do not require it. + The &os; Project utilizes + Bugzilla for tracking bugs and change + requests. Be sure that if you commit a fix or suggestion found + in the PR database to close it. It is also considered nice if + you take time to close any PRs associated with your commits, if + appropriate. - Tier 3 platforms must have the basics documented for how - to build a kernel and how to boot it on at least one target - hardware or emulation environment. This documentation need - not be integrated into the &os; tree. + Committers with + non-&os;.org + Bugzilla accounts can have the old account merged with the + &os;.org account by + entering a new bug. Choose + Supporting Services as the Product, and + Bug Tracker as the Component. - Current Tier 3 platforms are &arch.mips;, and - &arch.riscv;. - + You can find out more about + Bugzilla at: - - Tier 4: Unsupported Architectures + + + &os; + Problem Report Handling Guidelines + - Tier 4 systems are not supported in any form by the - project. + + http://www.freebsd.org/support.html + + + - All systems not otherwise classified into a support tier - are Tier 4 systems. The &arch.ia64; platform is transitioning - to Tier 4 status in &os; 11. - + + &coverity; Availability for &os; Committers - - Policy on Changing the Tier of an Architecture + All &os; developers can obtain access to + Coverity analysis results of all &os; + Project software. All who are interested in obtaining access to + the analysis results of the automated + Coverity runs, can sign up at Coverity + Scan. - Systems may only be moved from one tier to another by - approval of the &os; Core Team, which shall make that - decision in collaboration with the Security Officer, Release - Engineering, and toolchain maintenance teams. - + The &os; wiki includes a mini-guide for developers who are + interested in working with the &coverity; analysis reports: http://wiki.freebsd.org/CoverityPrevent. + Please note that this mini-guide is only readable by &os; + developers, so if you cannot access this page, you will have to + ask someone to add you to the appropriate Wiki access + list. + + Finally, all &os; developers who are going to use + &coverity; are always encouraged to ask for more details and + usage information, by posting any questions to the mailing list + of the &os; developers. @@ -4557,7 +4858,7 @@ merge. The script assumes that you can connect to - repo.FreeBSD.org with + repo.freebsd.org with SSH directly, so if your local login name is different than your &os; cluster account, you need a few lines in your @@ -4811,12 +5112,12 @@ The packages are built multiple times each week. If a port fails, the maintainer will receive an email from - pkg-fallout@FreeBSD.org. + pkg-fallout@freebsd.org. Reports for all the package builds (official, experimental, and non-regression) are aggregated at pkg-status.FreeBSD.org. + xlink:href="http://pkg-status.freebsd.org/">pkg-status.freebsd.org. @@ -4894,7 +5195,7 @@ Go to the Bugzilla + xlink:href="http://bugs.freebsd.org/submit">Bugzilla new PR page. @@ -4941,52 +5242,6 @@ - - Issues Specific to Developers Who Are Not - Committers - - A few people who have access to the &os; 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). In particular, - we recommend that you read: - - - - Administrative - Details - - - - Conventions - - - You should get your mentor to add you to the - Additional Contributors - (doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml), - if you are not already listed there. - - - - - Developer - Relations - - - - SSH Quick-Start - Guide - - - - The &os; Committers' Big List - of Rules - - - - - Information About &ga; @@ -5004,7 +5259,7 @@ Do Not Track header before fetching the tracking code from Google. For more information, please see the - &os; + &os; Privacy Policy. &ga; access is not arbitrarily @@ -5102,19 +5357,19 @@ How do I access people.FreeBSD.org to + class="fqdomainname">people.freebsd.org to put up personal or project information? people.FreeBSD.org is + class="fqdomainname">people.freebsd.org is the same as freefall.FreeBSD.org. + class="fqdomainname">freefall.freebsd.org. Just create a public_html directory. Anything you place in that directory will automatically be visible under http://people.FreeBSD.org/. + xlink:href="http://people.freebsd.org/">http://people.freebsd.org/. @@ -5127,72 +5382,10 @@ The mailing lists are archived under /local/mail on freefall.FreeBSD.org. - - - - - - I would like to mentor a new committer. What process - do I need to follow? - - - - See the New - Account Creation Procedure document on the - internal pages. + >freefall.freebsd.org. - - Benefits and Perks for &os; Comitters - - - Recognition - - Recognition as a competent software engineer is the - longest lasting value. In addition, getting a chance to work - with some of the best people that every engineer would dream - of meeting is a great perk! - - - - FreeBSD Mall - - &os; committers can get a free 4-CD or DVD set at - conferences from - &os; Mall, - Inc.. - - - - <acronym>IRC</acronym> - - In addition, developers may request a cloaked hostmask - for their account on the Freenode IRC network in the form - of - freebsd/developer/freefall - name or - freebsd/developer/NickServ - name. To request a cloak, send an email to - &a.irc.email; with your requested hostmask and NickServ - account name. - - - - <systemitem - class="domainname">Gandi.net</systemitem> - - Gandi provides website hosting, cloud computing, domain - registration, and X.509 certificate services. - - Gandi offers an E-rate discount to all &os; developers. - Send mail to non-profit@gandi.net using your - @freebsd.org mail address, and indicate - your Gandi handle. - -