os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes, translators please ignore.

Browse source
This commit is contained in:
Warren Block 2014-06-24 13:38:27 +00:00
parent 3056f51010
commit 3d1300b921
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45111
1 changed files with 145 additions and 132 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

277
en_US.ISO8859-1/articles/committers-guide/article.xml
View file

@ -209,19 +209,20 @@
<filename>doc/head/share/pgpkeys/checkkey.sh</filename> <filename>doc/head/share/pgpkeys/checkkey.sh</filename>
first.</para> first.</para>
<para>For those who do not yet have an Open<acronym>PGP</acronym> key, <para>For those who do not yet have an
or need a new key to meet &os; security requirements, here we Open<acronym>PGP</acronym> key, or need a new key to meet &os;
show how to generate one.</para> security requirements, here we show how to generate
one.</para>
<procedure xml:id="pgpkeys-create-steps"> <procedure xml:id="pgpkeys-create-steps">
<step> <step>
<para>Install <para>Install
<filename role="package">security/gnupg</filename>. Enter <filename role="package">security/gnupg</filename>. Enter
these lines in <filename>~/.gnupg/gpg.conf</filename> to set these lines in <filename>~/.gnupg/gpg.conf</filename> to
minimum acceptable defaults:</para> set minimum acceptable defaults:</para>
<programlisting>fixed-list-mode <programlisting>fixed-list-mode
keyid-format 0xlong keyid-format 0xlong
personal-digest-preferences SHA512 SHA384 SHA256 SHA224 personal-digest-preferences SHA512 SHA384 SHA256 SHA224
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed
@ -233,9 +234,9 @@ cert-digest-algo SHA512</programlisting>
</step> </step>
<step> <step>
<para>Generate a key:</para> <para>Generate a key:</para>
<screen>&prompt.user; <userinput>gpg --gen-key</userinput> <screen>&prompt.user; <userinput>gpg --gen-key</userinput>
gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc. gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it. This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law. There is NO WARRANTY, to the extent permitted by law.
@ -271,38 +272,39 @@ You selected this USER-ID:
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <userinput>o</userinput> Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <userinput>o</userinput>
You need a Passphrase to protect your secret key.</screen> You need a Passphrase to protect your secret key.</screen>
<calloutlist> <calloutlist>
<callout arearefs="co-pgp-bits"> <callout arearefs="co-pgp-bits">
<para>2048-bit keys with a three-year expiration provide <para>2048-bit keys with a three-year expiration provide
adequate protection at present (2013-12). <link adequate protection at present (2013-12). <link
xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/> xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/>
describes the situation in more detail.</para> describes the situation in more detail.</para>
</callout> </callout>
<callout arearefs="co-pgp-expire"> <callout arearefs="co-pgp-expire">
<para>A three year key lifespan is short enough to obsolete <para>A three year key lifespan is short enough to
keys weakened by advancing computer power, but long enough obsolete keys weakened by advancing computer power,
to reduce key management problems.</para> but long enough to reduce key management
</callout> problems.</para>
</callout>
<callout arearefs="co-pgp-realname"> <callout arearefs="co-pgp-realname">
<para>Use your real name here, preferably matching that <para>Use your real name here, preferably matching that
shown on government-issued <acronym>ID</acronym> to make shown on government-issued <acronym>ID</acronym> to
it easier for others to verify your identity. Text that make it easier for others to verify your identity.
may help others identify you can be entered in the Text that may help others identify you can be entered
<literal>Comment</literal> section.</para> in the <literal>Comment</literal> section.</para>
</callout> </callout>
</calloutlist> </calloutlist>
<para>After the email address is entered, a passphrase is <para>After the email address is entered, a passphrase is
requested. Methods of creating a secure passphrase are requested. Methods of creating a secure passphrase are
contentious. Rather than suggest a single way, here are some contentious. Rather than suggest a single way, here are
links to sites that describe various methods: <link some links to sites that describe various methods: <link
xlink:href="http://world.std.com/~reinhold/diceware.html"></link>, xlink:href="http://world.std.com/~reinhold/diceware.html"></link>,
<link <link
xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>, xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>,
<link xlink:href="http://xkcd.com/936/"></link>, <link <link xlink:href="http://xkcd.com/936/"></link>,
xlink:href=""></link>.</para> <link xlink:href=""></link>.</para>
</step> </step>
</procedure> </procedure>
@ -2207,8 +2209,8 @@ ControlPersist yes</screen>
<listitem> <listitem>
<para>The <filename>.ent</filename> and <para>The <filename>.ent</filename> and
<filename>.xml</filename> files mentioned below exist in the <filename>.xml</filename> files mentioned below exist in
&os; Documentation Project SVN repository at <link the &os; Documentation Project SVN repository at <link
xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para> xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para>
</listitem> </listitem>
@ -2219,20 +2221,20 @@ ControlPersist yes</screen>
when attempting to commit them to the repository. Be sure when attempting to commit them to the repository. Be sure
to read to read
<xref linkend="svn-daily-use-adding-and-removing"/> <xref linkend="svn-daily-use-adding-and-removing"/>
regarding adding and removing files. regarding adding and removing files. Verify that
Verify that <filename>~/.subversion/config</filename> <filename>~/.subversion/config</filename> contains the
contains the necessary <quote>auto-props</quote> entries from necessary <quote>auto-props</quote> entries from
<filename>auto-props.txt</filename> mentioned <filename>auto-props.txt</filename> mentioned
there.</para> there.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>All <filename>src</filename> commits should go to <para>All <filename>src</filename> commits should go to
&os.current; first before being merged to &os.stable;. &os.current; first before being merged to &os.stable;.
The &os.stable; branch must maintain <acronym>ABI</acronym> The &os.stable; branch must maintain
and <acronym>API</acronym> compatibility with earlier <acronym>ABI</acronym> and <acronym>API</acronym>
versions of that branch. Do not merge changes that break compatibility with earlier versions of that branch. Do
this compatibility.</para> not merge changes that break this compatibility.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -2242,43 +2244,50 @@ ControlPersist yes</screen>
<step> <step>
<title>Add an Author Entity</title> <title>Add an Author Entity</title>
<para><filename>head/share/xml/authors.ent</filename> &mdash; <para><filename>head/share/xml/authors.ent</filename>
Add an author entity. Later steps depend &mdash; Add an author entity. Later steps depend on this
on this entity, and missing this step will entity, and missing this step will cause the
cause the <filename>doc/</filename> build to fail. This is a
<filename>doc/</filename> build to fail. This is a relatively easy task, but remains a good relatively easy task, but remains a good first test of
first test of version control skills.</para> version control skills.</para>
</step> </step>
<step> <step>
<title>Update the List of Developers and Contributors</title> <title>Update the List of Developers and
Contributors</title>
<para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename> &mdash; <para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>
&mdash;
Add an entry to the <quote>Developers</quote> section Add an entry to the <quote>Developers</quote> section
of the <link of the <link
xlink:href="&url.articles.contributors;/staff-committers.html">Contributors xlink:href="&url.articles.contributors;/staff-committers.html">Contributors
List</link>. Entries are sorted by last name.</para> List</link>. Entries are sorted by last name.</para>
<para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename> &mdash;
Remove the entry from the <para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>
<quote>Additional Contributors</quote> section. &mdash; Remove the entry from the
Entries are sorted by last name.</para> <quote>Additional Contributors</quote> section. Entries
are sorted by last name.</para>
</step> </step>
<step> <step>
<title>Add a News Item</title> <title>Add a News Item</title>
<para><filename>doc/head/share/xml/news.xml</filename> &mdash;
Add an entry. Look for <para><filename>doc/head/share/xml/news.xml</filename>
the other entries that announce &mdash; Add an entry. Look for the other entries that
new committers and follow the announce new committers and follow the format. Use the
format. Use the date from the commit bit approval email from <email>core@FreeBSD.org</email>.</para> date from the commit bit approval email from
<email>core@FreeBSD.org</email>.</para>
</step> </step>
<step> <step>
<title>Add a <acronym>PGP</acronym> Key</title> <title>Add a <acronym>PGP</acronym> Key</title>
<para><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename> and
<filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename> - <para><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename>
Add your <acronym>PGP</acronym> or Gnu<acronym>PG</acronym> key. and
Those who do not yet have a key should see <xref linkend="pgpkeys-creating"/>.</para> <filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename>
- Add your <acronym>PGP</acronym> or
Gnu<acronym>PG</acronym> key. Those who do not yet have a
key should see <xref linkend="pgpkeys-creating"/>.</para>
<para>&a.des.email; has written a shell script <para>&a.des.email; has written a shell script
(<filename>head/share/pgpkeys/addkey.sh</filename>) to (<filename>head/share/pgpkeys/addkey.sh</filename>) to
@ -2291,15 +2300,17 @@ ControlPersist yes</screen>
verify that keys meet minimal best-practices verify that keys meet minimal best-practices
standards.</para> standards.</para>
<para>After adding and checking a key, add both updated files to source control and then commit them. <para>After adding and checking a key, add both updated
Entries in this file are sorted by last name.</para> files to source control and then commit them. Entries in
this file are sorted by last name.</para>
<note> <note>
<para>It is very important to have a current <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key <para>It is very important to have a current
in the repository. The key may be required for <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key in
positive identification of a committer. For example, the the repository. The key may be required for positive
&a.admins; might need it for account recovery. A complete keyring of identification of a committer. For example, the
<systemitem &a.admins; might need it for account recovery. A
complete keyring of <systemitem
class="fqdomainname">FreeBSD.org</systemitem> users is class="fqdomainname">FreeBSD.org</systemitem> users is
available for download from <link available for download from <link
xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para> xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
@ -2309,43 +2320,41 @@ ControlPersist yes</screen>
<step> <step>
<title>Update Mentor and Mentee Information</title> <title>Update Mentor and Mentee Information</title>
<para><filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename> &mdash; <para><filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>
Add an entry to the current committers &mdash; Add an entry to the current committers section,
section, where <replaceable>repository</replaceable> is
where <replaceable>repository</replaceable> is <literal>doc</literal>, <literal>ports</literal>, or <literal>src</literal>, depending on <literal>doc</literal>, <literal>ports</literal>, or
the commit privileges granted.</para> <literal>src</literal>, depending on the commit privileges
granted.</para>
<para>Add an entry for the <para>Add an entry for the each additonal mentor/mentee
each additonal mentor/mentee relationship in the relationship in the bottom section.</para>
bottom section.</para>
</step> </step>
<step> <step>
<title>Generate a <application>Kerberos</application> <title>Generate a <application>Kerberos</application>
Password</title> Password</title>
<para>See <xref linkend="kerberos-ldap"/> to generate or <para>See <xref linkend="kerberos-ldap"/> to generate or
set a <application>Kerberos</application> for use with set a <application>Kerberos</application> for use with
other &os; services like the bug tracking other &os; services like the bug tracking database.</para>
database.</para>
</step> </step>
<step> <step>
<title>Optional: Enable Wiki Account</title> <title>Optional: Enable Wiki Account</title>
<para><link xlink:href="http://wiki.freebsd.org">&os; Wiki</link> Account &mdash; <para><link xlink:href="http://wiki.freebsd.org">&os;
A wiki account allows sharing projects and ideas. Those Wiki</link> Account &mdash; A wiki account allows
who do not yet have an account can contact sharing projects and ideas. Those who do not yet have an
<email>clusteradm@FreeBSD.org</email> to obtain account can contact <email>clusteradm@FreeBSD.org</email>
one.</para> to obtain one.</para>
</step> </step>
<step> <step>
<title>Optional: Update Wiki Information</title> <title>Optional: Update Wiki Information</title>
<para>Wiki Information - <para>Wiki Information - After gaining access to the wiki,
After gaining access to the wiki, some people add entries some people add entries to the <link
to the <link
xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
Got Here</link>, Got Here</link>,
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc <link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
@ -2355,20 +2364,24 @@ ControlPersist yes</screen>
</step> </step>
<step> <step>
<title>Optional: Update Ports with Personal Information</title> <title>Optional: Update Ports with Personal
<para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename> and Information</title>
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename> -
Some people add entries for themselves to these <para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename>
files to show where they are located or the date of their birthday.</para> and
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>
- Some people add entries for themselves to these files to
show where they are located or the date of their
birthday.</para>
</step> </step>
<step> <step>
<title>Optional: Prevent Duplicate Mailings</title> <title>Optional: Prevent Duplicate Mailings</title>
<para>Subscribers to &a.svn-src-all.name;, <para>Subscribers to &a.svn-src-all.name;,
&a.svn-ports-all.name; or &a.svn-doc-all.name; might wish to &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish
unsubscribe to avoid receiving duplicate to unsubscribe to avoid receiving duplicate copies of
copies of commit messages and followups.</para> commit messages and followups.</para>
</step> </step>
</procedure> </procedure>
</sect2> </sect2>
@ -2381,11 +2394,10 @@ ControlPersist yes</screen>
<para>Introduce yourself to the other developers, otherwise <para>Introduce yourself to the other developers, otherwise
no one will have any idea who you are or what you are no one will have any idea who you are or what you are
working on. The introduction need not be a comprehensive working on. The introduction need not be a comprehensive
biography, just write a paragraph or two about who you are, biography, just write a paragraph or two about who you
what you plan to be working on as a developer in are, what you plan to be working on as a developer in
&os;, and who will be your mentor. &os;, and who will be your mentor. Email this to the
Email this to the &a.developers; and you will be on &a.developers; and you will be on your way!</para>
your way!</para>
</step> </step>
<step> <step>
@ -2432,20 +2444,20 @@ ControlPersist yes</screen>
<para>All new developers have a mentor assigned to them for <para>All new developers have a mentor assigned to them for
the first few months. A mentor is responsible for teaching the first few months. A mentor is responsible for teaching
the mentee the rules and conventions of the project and guiding their the mentee the rules and conventions of the project and
first steps in the developer community. The mentor is also guiding their first steps in the developer community. The
personally responsible for the mentee's actions during this initial mentor is also personally responsible for the mentee's actions
period.</para> during this initial period.</para>
<para>For committers: do not commit anything without first <para>For committers: do not commit anything without first
getting mentor approval. Document that getting mentor approval. Document that approval with an
approval with an <literal>Approved by:</literal> line in the <literal>Approved by:</literal> line in the commit
commit message.</para> message.</para>
<para>When the mentor decides that a mentee has learned the <para>When the mentor decides that a mentee has learned the
ropes and is ready to commit on their own, the mentor ropes and is ready to commit on their own, the mentor
announces it announces it with a commit to
with a commit to <filename>mentors</filename>.</para> <filename>mentors</filename>.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -2724,7 +2736,8 @@ Relnotes: yes</programlisting>
</sect1> </sect1>
<sect1 xml:id="tracking.license.grants"> <sect1 xml:id="tracking.license.grants">
<title>Keeping Track of Licenses Granted to the &os; Project</title> <title>Keeping Track of Licenses Granted to the &os;
Project</title>
<para>Various software or data exist in the repositories where <para>Various software or data exist in the repositories where
the &os; project has been granted a special licence to be able the &os; project has been granted a special licence to be able
@ -2738,8 +2751,8 @@ Relnotes: yes</programlisting>
license grants. To that end, the &a.core; has decided to keep license grants. To that end, the &a.core; has decided to keep
an archive of them. Whenever the &os; project is granted a an archive of them. Whenever the &os; project is granted a
special license we require the &a.core; to be notified. Any special license we require the &a.core; to be notified. Any
developers involved in arranging such a license grant, please send developers involved in arranging such a license grant, please
details to the &a.core; including:</para> send details to the &a.core; including:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2755,8 +2768,8 @@ Relnotes: yes</programlisting>
<listitem> <listitem>
<para>The date the license comes into effect from. Unless <para>The date the license comes into effect from. Unless
otherwise agreed, this will be the date the license was issued otherwise agreed, this will be the date the license was
by the authors of the software in question.</para> issued by the authors of the software in question.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -2764,8 +2777,8 @@ Relnotes: yes</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>A note of any restrictions, limitations or exceptions that <para>A note of any restrictions, limitations or exceptions
apply specifically to &os;'s usage of the licensed that apply specifically to &os;'s usage of the licensed
material.</para> material.</para>
</listitem> </listitem>
@ -2774,11 +2787,11 @@ Relnotes: yes</programlisting>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Once the &a.core; is satisfied that all the necessary details <para>Once the &a.core; is satisfied that all the necessary
have been gathered and are correct, the secretary will send a details have been gathered and are correct, the secretary will
PGP-signed acknowledgement of receipt including the license send a PGP-signed acknowledgement of receipt including the
details. This receipt will be persistently archived and serve license details. This receipt will be persistently archived and
as our permanent record of the license grant.</para> serve as our permanent record of the license grant.</para>
<para>The license archive should contain only details of license <para>The license archive should contain only details of license
grants; this is not the place for any discussions around grants; this is not the place for any discussions around