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>
first.</para>
<para>For those who do not yet have an Open<acronym>PGP</acronym> key,
or need a new key to meet &os; security requirements, here we
show how to generate one.</para>
<para>For those who do not yet have an
Open<acronym>PGP</acronym> key, or need a new key to meet &os;
security requirements, here we show how to generate
one.</para>
<procedure xml:id="pgpkeys-create-steps">
<step>
<para>Install
<filename role="package">security/gnupg</filename>. Enter
these lines in <filename>~/.gnupg/gpg.conf</filename> to set
minimum acceptable defaults:</para>
<para>Install
<filename role="package">security/gnupg</filename>. Enter
these lines in <filename>~/.gnupg/gpg.conf</filename> to
set minimum acceptable defaults:</para>
<programlisting>fixed-list-mode
<programlisting>fixed-list-mode
keyid-format 0xlong
personal-digest-preferences SHA512 SHA384 SHA256 SHA224
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>
<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.
This is free software: you are free to change and redistribute it.
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>
You need a Passphrase to protect your secret key.</screen>
<calloutlist>
<callout arearefs="co-pgp-bits">
<para>2048-bit keys with a three-year expiration provide
adequate protection at present (2013-12). <link
xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/>
describes the situation in more detail.</para>
</callout>
<calloutlist>
<callout arearefs="co-pgp-bits">
<para>2048-bit keys with a three-year expiration provide
adequate protection at present (2013-12). <link
xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/>
describes the situation in more detail.</para>
</callout>
<callout arearefs="co-pgp-expire">
<para>A three year key lifespan is short enough to obsolete
keys weakened by advancing computer power, but long enough
to reduce key management problems.</para>
</callout>
<callout arearefs="co-pgp-expire">
<para>A three year key lifespan is short enough to
obsolete keys weakened by advancing computer power,
but long enough to reduce key management
problems.</para>
</callout>
<callout arearefs="co-pgp-realname">
<para>Use your real name here, preferably matching that
shown on government-issued <acronym>ID</acronym> to make
it easier for others to verify your identity. Text that
may help others identify you can be entered in the
<literal>Comment</literal> section.</para>
</callout>
</calloutlist>
<callout arearefs="co-pgp-realname">
<para>Use your real name here, preferably matching that
shown on government-issued <acronym>ID</acronym> to
make it easier for others to verify your identity.
Text that may help others identify you can be entered
in the <literal>Comment</literal> section.</para>
</callout>
</calloutlist>
<para>After the email address is entered, a passphrase is
requested. Methods of creating a secure passphrase are
contentious. Rather than suggest a single way, here are some
links to sites that describe various methods: <link
xlink:href="http://world.std.com/~reinhold/diceware.html"></link>,
<link
xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>,
<link xlink:href="http://xkcd.com/936/"></link>, <link
xlink:href=""></link>.</para>
<para>After the email address is entered, a passphrase is
requested. Methods of creating a secure passphrase are
contentious. Rather than suggest a single way, here are
some links to sites that describe various methods: <link
xlink:href="http://world.std.com/~reinhold/diceware.html"></link>,
<link
xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>,
<link xlink:href="http://xkcd.com/936/"></link>,
<link xlink:href=""></link>.</para>
</step>
</procedure>
@ -2207,8 +2209,8 @@ ControlPersist yes</screen>
<listitem>
<para>The <filename>.ent</filename> and
<filename>.xml</filename> files mentioned below exist in the
&os; Documentation Project SVN repository at <link
<filename>.xml</filename> files mentioned below exist in
the &os; Documentation Project SVN repository at <link
xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para>
</listitem>
@ -2219,20 +2221,20 @@ ControlPersist yes</screen>
when attempting to commit them to the repository. Be sure
to read
<xref linkend="svn-daily-use-adding-and-removing"/>
regarding adding and removing files.
Verify that <filename>~/.subversion/config</filename>
contains the necessary <quote>auto-props</quote> entries from
regarding adding and removing files. Verify that
<filename>~/.subversion/config</filename> contains the
necessary <quote>auto-props</quote> entries from
<filename>auto-props.txt</filename> mentioned
there.</para>
</listitem>
<listitem>
<para>All <filename>src</filename> commits should go to
&os.current; first before being merged to &os.stable;.
The &os.stable; branch must maintain <acronym>ABI</acronym>
and <acronym>API</acronym> compatibility with earlier
versions of that branch. Do not merge changes that break
this compatibility.</para>
<para>All <filename>src</filename> commits should go to
&os.current; first before being merged to &os.stable;.
The &os.stable; branch must maintain
<acronym>ABI</acronym> and <acronym>API</acronym>
compatibility with earlier versions of that branch. Do
not merge changes that break this compatibility.</para>
</listitem>
</itemizedlist>
@ -2242,43 +2244,50 @@ ControlPersist yes</screen>
<step>
<title>Add an Author Entity</title>
<para><filename>head/share/xml/authors.ent</filename> &mdash;
Add an author entity. Later steps depend
on this entity, and missing this step will
cause the
<filename>doc/</filename> build to fail. This is a relatively easy task, but remains a good
first test of version control skills.</para>
<para><filename>head/share/xml/authors.ent</filename>
&mdash; Add an author entity. Later steps depend on this
entity, and missing this step will cause the
<filename>doc/</filename> build to fail. This is a
relatively easy task, but remains a good first test of
version control skills.</para>
</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
of the <link
xlink:href="&url.articles.contributors;/staff-committers.html">Contributors
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
<quote>Additional Contributors</quote> section.
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
<quote>Additional Contributors</quote> section. Entries
are sorted by last name.</para>
</step>
<step>
<title>Add a News Item</title>
<para><filename>doc/head/share/xml/news.xml</filename> &mdash;
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 <email>core@FreeBSD.org</email>.</para>
<para><filename>doc/head/share/xml/news.xml</filename>
&mdash; 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
<email>core@FreeBSD.org</email>.</para>
</step>
<step>
<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> -
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><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename>
and
<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
(<filename>head/share/pgpkeys/addkey.sh</filename>) to
@ -2291,15 +2300,17 @@ ControlPersist yes</screen>
verify that keys meet minimal best-practices
standards.</para>
<para>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.</para>
<para>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.</para>
<note>
<para>It is very important to have a current <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> 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
<systemitem
<para>It is very important to have a current
<acronym>PGP</acronym>/Gnu<acronym>PG</acronym> 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 <systemitem
class="fqdomainname">FreeBSD.org</systemitem> users is
available for download from <link
xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
@ -2309,43 +2320,41 @@ ControlPersist yes</screen>
<step>
<title>Update Mentor and Mentee Information</title>
<para><filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename> &mdash;
Add an entry to the current committers
section,
where <replaceable>repository</replaceable> is <literal>doc</literal>, <literal>ports</literal>, or <literal>src</literal>, depending on
the commit privileges granted.</para>
<para><filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>
&mdash; Add an entry to the current committers section,
where <replaceable>repository</replaceable> is
<literal>doc</literal>, <literal>ports</literal>, or
<literal>src</literal>, depending on the commit privileges
granted.</para>
<para>Add an entry for the
each additonal mentor/mentee relationship in the
bottom section.</para>
<para>Add an entry for the each additonal mentor/mentee
relationship in the bottom section.</para>
</step>
<step>
<title>Generate a <application>Kerberos</application>
Password</title>
<para>See <xref linkend="kerberos-ldap"/> to generate or
set a <application>Kerberos</application> for use with
other &os; services like the bug tracking
database.</para>
<para>See <xref linkend="kerberos-ldap"/> to generate or
set a <application>Kerberos</application> for use with
other &os; services like the bug tracking database.</para>
</step>
<step>
<title>Optional: Enable Wiki Account</title>
<para><link xlink:href="http://wiki.freebsd.org">&os; Wiki</link> Account &mdash;
A wiki account allows sharing projects and ideas. Those
who do not yet have an account can contact
<email>clusteradm@FreeBSD.org</email> to obtain
one.</para>
<para><link xlink:href="http://wiki.freebsd.org">&os;
Wiki</link> Account &mdash; A wiki account allows
sharing projects and ideas. Those who do not yet have an
account can contact <email>clusteradm@FreeBSD.org</email>
to obtain one.</para>
</step>
<step>
<title>Optional: Update Wiki Information</title>
<para>Wiki Information -
After gaining access to the wiki, some people add entries
to the <link
<para>Wiki Information - After gaining access to the wiki,
some people add entries to the <link
xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
Got Here</link>,
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
@ -2355,20 +2364,24 @@ ControlPersist yes</screen>
</step>
<step>
<title>Optional: Update Ports with Personal Information</title>
<para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename> 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>
<title>Optional: Update Ports with Personal
Information</title>
<para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename>
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>
<title>Optional: Prevent Duplicate Mailings</title>
<para>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.</para>
&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.</para>
</step>
</procedure>
</sect2>
@ -2381,11 +2394,10 @@ ControlPersist yes</screen>
<para>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!</para>
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!</para>
</step>
<step>
@ -2432,20 +2444,20 @@ ControlPersist yes</screen>
<para>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.</para>
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.</para>
<para>For committers: do not commit anything without first
getting mentor approval. Document that
approval with an <literal>Approved by:</literal> line in the
commit message.</para>
getting mentor approval. Document that approval with an
<literal>Approved by:</literal> line in the commit
message.</para>
<para>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 <filename>mentors</filename>.</para>
announces it with a commit to
<filename>mentors</filename>.</para>
</sect2>
</sect1>
@ -2724,7 +2736,8 @@ Relnotes: yes</programlisting>
</sect1>
<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
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
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:</para>
developers involved in arranging such a license grant, please
send details to the &a.core; including:</para>
<itemizedlist>
<listitem>
@ -2755,8 +2768,8 @@ Relnotes: yes</programlisting>
<listitem>
<para>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.</para>
otherwise agreed, this will be the date the license was
issued by the authors of the software in question.</para>
</listitem>
<listitem>
@ -2764,8 +2777,8 @@ Relnotes: yes</programlisting>
</listitem>
<listitem>
<para>A note of any restrictions, limitations or exceptions that
apply specifically to &os;'s usage of the licensed
<para>A note of any restrictions, limitations or exceptions
that apply specifically to &os;'s usage of the licensed
material.</para>
</listitem>
@ -2774,11 +2787,11 @@ Relnotes: yes</programlisting>
</listitem>
</itemizedlist>
<para>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.</para>
<para>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.</para>
<para>The license archive should contain only details of license
grants; this is not the place for any discussions around