diff --git a/en_US.ISO8859-1/articles/committers-guide/Makefile b/en_US.ISO8859-1/articles/committers-guide/Makefile new file mode 100644 index 0000000000..8b6f06af66 --- /dev/null +++ b/en_US.ISO8859-1/articles/committers-guide/Makefile @@ -0,0 +1,25 @@ +# +# $Id: Makefile,v 1.1 1999-09-03 17:10:42 nik Exp $ +# +# Build the FreeBSD New Committers Guide +# + +MAINTAINER=jhb@FreeBSD.org + +DOC?= article + +FORMATS?= html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= article.sgml + +DOC_PREFIX?= ../../.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml new file mode 100644 index 0000000000..17533ba308 --- /dev/null +++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml @@ -0,0 +1,404 @@ + +%man; + + +%authors; +]> + +
+ + New Committer Guide + + + + The FreeBSD Documentation Project + + + + September 1999 + + + 1999 + The FreeBSD Documentation Project + + + + Welcome, new committer, to the FreeBSD development + team! + + The following docs are provided to orient you on doing CVS + operations on the FreeBSD central repository machine. A basic + familiarity with CVS is already assumed, although CVS + reference information, tutorials, and FAQs can also be found + at: http://www.cyclic.com/cyclic-pages/books.html + + Good luck, and welcome aboard! + + + + + Administrative Details + + + + + + Repository Host + freefall.FreeBSD.org + + + + Login Methods + &man.ssh.1; + + + + CVSROOT + /home/ncvs + + + + CVS Repository Meisters + &a.jdp; and &a.peter; + + + + Mailing List + cvs-committers@FreeBSD.org + [which you are now on] + + + + Mentor Name + &a.jkh; + + + + Noteworthy CVS Tags + RELENG_3 (3.x-STABLE), HEAD (-CURRENT) + + + + + + It is required that you use &man.ssh.1; with public key + authentication to access the repository host. This is generally + more secure than &man.telnet.1; or &man.rlogin.1; since your + connection will always be encrypted. With utilities like + &man.ssh-agent.1; and &man.scp.1; also available, it is also far + more convenient. If you do not know anything about &man.ssh.1, + please see . + + + + CVS Operations + + CVS operations are usually done by logging into + freefall, making sure the + CVSROOT environment variable is set to + /home/ncvs, and then doing the appropriate + check-out/check-in operations. If you wish to add + something which is wholly new (like new ports, contrib-ified + sources, etc), a script called easy-import is + also provided for making the process easier. It automatically + adds the new module entry, does the appropriate thing with + cvs import, etc. – just run it without + arguments and it will prompt you for everything it needs to + know. + + If you are familiar with remote CVS and consider yourself + pretty studly with CVS in general, you can also do CVS + operations directly from your own machine and local working + sources. Just remember to set CVS_RSH to + ssh so that you are using a relatively + secure and reliable transport. If you have no idea what any of + the above even means, on the other hand, then please stick with + logging into freefall and applying your diffs + with &man.patch.1;. + + If you need to use CVS add and + delete operations in a manner that is + effectively a mv operation, then a repository + copy is in order rather than your CVS add and + delete. In a repository copy, a CVS Meister will copy the file(s) + to their new name and/or location and let you know when it is + done. The purpose of a repository copy is to preserve file + change history, or logs. We in the FreeBSD Project greatly + value the change history CVS gives to the project. + + + + Conventions and Traditions + + The CVS Repository Meisters (Peter Wemm and John Polstra) + are the owners of the CVS repository and + responsible for any and all direct + modification of it for the purposes of cleanup or fixing some + grievous abuse of CVS by a committer. No one else should + attempt to touch the repository directly. Should you cause some + repository accident, say a bad cvs import or tag operation, do + not attempt to fix it yourself! + Mail or call John or Peter immediately and report the problem to + one of them instead. The only ones allowed to directly fiddle + the repository bits are the repomeisters. + + If you are a new committer, your very first commit should be + to add yourself to the developer's section (28.2) of the + Handbook. Figuring out how to check the handbook out and add an + entry for yourself is relatively easy but still remains a good + first test of your CVS skills. If you can handle that one, + you are probably going to be ok. + + Your next step should be to introduce yourself to the other + committers, otherwise no one will have any idea who you are or + what you are working on. You do not have to write a comprehensive + biography, just write a paragraph or two about who you are and + what you plan to be working on as a committer in FreeBSD. Email + this to cvs-committers@FreeBSD.org and you will be on + your way! + + Also, be sure to log into hub.FreeBSD.org + and create yourself a + /var/forward/user + (where user is your username) file + which contains your principal e-mail address where you want mail + to yourusername@FreeBSD.org + to be forwarded. Really large mailboxes which have taken up + permanent residence on hub often get + accidently truncated without warning, so forward + it or read it and you will not lose it. + + All new committers also have a mentor assigned to them for + the first few months. The name of your mentor listed at the top + of this message. Your mentor is more or less responsible for + explaining anything which is confusing to you and is also + responsible for your actions during this initial period. If you + make a bogus commit, it is only going to embarrass your mentor + and you should probably make it a policy to pass at least your + first few commits by your mentor before committing it to the + repository. + + All commits should go to -CURRENT first + before being merged to -STABLE. No major new + features or high-risk modifications should be made to the + -STABLE branch. + + + + Developer Relations + + 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 + cvs-all 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 output of cvs log + to see who has committed changes in the past. If your queries go + unanswered or the committer otherwise indicates a lack of + proprietary interest in the area affected, go ahead and commit + it. + + If you are at all unsure about a commit for any reason in + general, have it reviewed by -hackers first + before committing. Better to have it flamed then and there + rather than when it is part of the CVS 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 CVS we + can always change it back. + + + + GNATS + + The FreeBSD Project utilizes + GNATS for tracking bugs and change + requests. Be sure that if you commit a fix or suggestion found + in a GNATS PR, you use + edit-pr pr-number + on freefall to close it. It is also considered + nice if you take time to close any PRs associated with your + commits, if appropriate. Your can also make use of + &man.send-pr.1; yourself for proposing any change which you feel + should probably be made, pending a more extensive peer-review + first. + + You can find out more about GNATS + at: + + + + http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html + + + + http://www.FreeBSD.org/support.html + + + + http://www.FreeBSD.org/send-pr.html + + + + &man.send-pr.1; + + + + + + Who's Who + + Besides Peter Wemm and John Polstra, the repository + meisters, there are other FreeBSD project members whom you will + probably get to know in your new role as a committer. Briefly, + and by no means all-inclusively, these are: + + + + &a.asami; + + + Is the portsmeister, meaning that he has ultimate + authority during code freezes over any modifications to the + ports collection or ports make macro files. + + + + + &a.bde; + + + Is Obersturmbahnfuhrer of the Style Police. When you + do a commit that could have been done better, Bruce will + be there to note it to you. Be thankful that someone + is. + + + + + &a.dg; + + + Is our principal architect and overseer of the VM + system. If you have a VM system change in mind, + coordinate it with David. Should you become locked in + bitter, intractable dispute with some other committer over + a proposed change (which does not happen very often, + thankfully) then an appeal to David to put on his P.A. hat + and make a final decision can also occasionally be + necessary. + + + + + &a.jkh; + + + Is the release engineer. He is responsible for + setting release deadlines and controlling the release + process. During code freezes, he also has final authority + on all changes to the system for whichever branch is + pending release status. If there is something you want + merged from -CURRENT to + -STABLE (whatever values those may have + at any given time), he is also the one to talk to about + it + + + + + &a.steve; + + + Steve is unofficial maintainer of + /usr/src/bin. If you have something + significant you'd like to do there, you should probably + coordinate it first with Steve. He's also Problem + Report-meister, along with &a.phk;. + + + + + &a.brian; + + + Official maintainer of + /usr/bin/ppp and LPD. + + + + + &a.wollman; + + + If you need advice on obscure network internals or + aren't sure of some potential change to the networking + subsystem you have in mind, Garrett is someone to talk + to. + + + + + + + SSH Quick-Start Guide + + + + Update and install the ssh port in + /usr/ports/security/ssh (should be + version 1.2.25 or later). + + + + Make sure that you run &man.ssh-agent.1; before running + other applications. X users, for example, usually do this + from their .xsession or + .xinitrc file. See &man.ssh-agent.1; + for details. + + + + Generate a key pair using &man.ssh-keygen.1;. The key + pair will wind up in the + $HOME/.ssh + directory. + + + + Copy your public key + ($HOME/.ssh/identity.pub) + into your authorized_keys file in your + home directory on freefall + (i.e. + $HOME/.ssh/authorized_keys). + + + + + 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;) so that you won't + have to retype it over and over. + + Test by doing something such as ssh + freefall.FreeBSD.org ls /usr. + + For more information, see + /usr/ports/security/ssh, &man.ssh.1;, + &man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;. + +
diff --git a/en_US.ISO_8859-1/articles/committers-guide/Makefile b/en_US.ISO_8859-1/articles/committers-guide/Makefile new file mode 100644 index 0000000000..8b6f06af66 --- /dev/null +++ b/en_US.ISO_8859-1/articles/committers-guide/Makefile @@ -0,0 +1,25 @@ +# +# $Id: Makefile,v 1.1 1999-09-03 17:10:42 nik Exp $ +# +# Build the FreeBSD New Committers Guide +# + +MAINTAINER=jhb@FreeBSD.org + +DOC?= article + +FORMATS?= html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= article.sgml + +DOC_PREFIX?= ../../.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO_8859-1/articles/committers-guide/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml new file mode 100644 index 0000000000..17533ba308 --- /dev/null +++ b/en_US.ISO_8859-1/articles/committers-guide/article.sgml @@ -0,0 +1,404 @@ + +%man; + + +%authors; +]> + +
+ + New Committer Guide + + + + The FreeBSD Documentation Project + + + + September 1999 + + + 1999 + The FreeBSD Documentation Project + + + + Welcome, new committer, to the FreeBSD development + team! + + The following docs are provided to orient you on doing CVS + operations on the FreeBSD central repository machine. A basic + familiarity with CVS is already assumed, although CVS + reference information, tutorials, and FAQs can also be found + at: http://www.cyclic.com/cyclic-pages/books.html + + Good luck, and welcome aboard! + + + + + Administrative Details + + + + + + Repository Host + freefall.FreeBSD.org + + + + Login Methods + &man.ssh.1; + + + + CVSROOT + /home/ncvs + + + + CVS Repository Meisters + &a.jdp; and &a.peter; + + + + Mailing List + cvs-committers@FreeBSD.org + [which you are now on] + + + + Mentor Name + &a.jkh; + + + + Noteworthy CVS Tags + RELENG_3 (3.x-STABLE), HEAD (-CURRENT) + + + + + + It is required that you use &man.ssh.1; with public key + authentication to access the repository host. This is generally + more secure than &man.telnet.1; or &man.rlogin.1; since your + connection will always be encrypted. With utilities like + &man.ssh-agent.1; and &man.scp.1; also available, it is also far + more convenient. If you do not know anything about &man.ssh.1, + please see . + + + + CVS Operations + + CVS operations are usually done by logging into + freefall, making sure the + CVSROOT environment variable is set to + /home/ncvs, and then doing the appropriate + check-out/check-in operations. If you wish to add + something which is wholly new (like new ports, contrib-ified + sources, etc), a script called easy-import is + also provided for making the process easier. It automatically + adds the new module entry, does the appropriate thing with + cvs import, etc. – just run it without + arguments and it will prompt you for everything it needs to + know. + + If you are familiar with remote CVS and consider yourself + pretty studly with CVS in general, you can also do CVS + operations directly from your own machine and local working + sources. Just remember to set CVS_RSH to + ssh so that you are using a relatively + secure and reliable transport. If you have no idea what any of + the above even means, on the other hand, then please stick with + logging into freefall and applying your diffs + with &man.patch.1;. + + If you need to use CVS add and + delete operations in a manner that is + effectively a mv operation, then a repository + copy is in order rather than your CVS add and + delete. In a repository copy, a CVS Meister will copy the file(s) + to their new name and/or location and let you know when it is + done. The purpose of a repository copy is to preserve file + change history, or logs. We in the FreeBSD Project greatly + value the change history CVS gives to the project. + + + + Conventions and Traditions + + The CVS Repository Meisters (Peter Wemm and John Polstra) + are the owners of the CVS repository and + responsible for any and all direct + modification of it for the purposes of cleanup or fixing some + grievous abuse of CVS by a committer. No one else should + attempt to touch the repository directly. Should you cause some + repository accident, say a bad cvs import or tag operation, do + not attempt to fix it yourself! + Mail or call John or Peter immediately and report the problem to + one of them instead. The only ones allowed to directly fiddle + the repository bits are the repomeisters. + + If you are a new committer, your very first commit should be + to add yourself to the developer's section (28.2) of the + Handbook. Figuring out how to check the handbook out and add an + entry for yourself is relatively easy but still remains a good + first test of your CVS skills. If you can handle that one, + you are probably going to be ok. + + Your next step should be to introduce yourself to the other + committers, otherwise no one will have any idea who you are or + what you are working on. You do not have to write a comprehensive + biography, just write a paragraph or two about who you are and + what you plan to be working on as a committer in FreeBSD. Email + this to cvs-committers@FreeBSD.org and you will be on + your way! + + Also, be sure to log into hub.FreeBSD.org + and create yourself a + /var/forward/user + (where user is your username) file + which contains your principal e-mail address where you want mail + to yourusername@FreeBSD.org + to be forwarded. Really large mailboxes which have taken up + permanent residence on hub often get + accidently truncated without warning, so forward + it or read it and you will not lose it. + + All new committers also have a mentor assigned to them for + the first few months. The name of your mentor listed at the top + of this message. Your mentor is more or less responsible for + explaining anything which is confusing to you and is also + responsible for your actions during this initial period. If you + make a bogus commit, it is only going to embarrass your mentor + and you should probably make it a policy to pass at least your + first few commits by your mentor before committing it to the + repository. + + All commits should go to -CURRENT first + before being merged to -STABLE. No major new + features or high-risk modifications should be made to the + -STABLE branch. + + + + Developer Relations + + 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 + cvs-all 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 output of cvs log + to see who has committed changes in the past. If your queries go + unanswered or the committer otherwise indicates a lack of + proprietary interest in the area affected, go ahead and commit + it. + + If you are at all unsure about a commit for any reason in + general, have it reviewed by -hackers first + before committing. Better to have it flamed then and there + rather than when it is part of the CVS 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 CVS we + can always change it back. + + + + GNATS + + The FreeBSD Project utilizes + GNATS for tracking bugs and change + requests. Be sure that if you commit a fix or suggestion found + in a GNATS PR, you use + edit-pr pr-number + on freefall to close it. It is also considered + nice if you take time to close any PRs associated with your + commits, if appropriate. Your can also make use of + &man.send-pr.1; yourself for proposing any change which you feel + should probably be made, pending a more extensive peer-review + first. + + You can find out more about GNATS + at: + + + + http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html + + + + http://www.FreeBSD.org/support.html + + + + http://www.FreeBSD.org/send-pr.html + + + + &man.send-pr.1; + + + + + + Who's Who + + Besides Peter Wemm and John Polstra, the repository + meisters, there are other FreeBSD project members whom you will + probably get to know in your new role as a committer. Briefly, + and by no means all-inclusively, these are: + + + + &a.asami; + + + Is the portsmeister, meaning that he has ultimate + authority during code freezes over any modifications to the + ports collection or ports make macro files. + + + + + &a.bde; + + + Is Obersturmbahnfuhrer of the Style Police. When you + do a commit that could have been done better, Bruce will + be there to note it to you. Be thankful that someone + is. + + + + + &a.dg; + + + Is our principal architect and overseer of the VM + system. If you have a VM system change in mind, + coordinate it with David. Should you become locked in + bitter, intractable dispute with some other committer over + a proposed change (which does not happen very often, + thankfully) then an appeal to David to put on his P.A. hat + and make a final decision can also occasionally be + necessary. + + + + + &a.jkh; + + + Is the release engineer. He is responsible for + setting release deadlines and controlling the release + process. During code freezes, he also has final authority + on all changes to the system for whichever branch is + pending release status. If there is something you want + merged from -CURRENT to + -STABLE (whatever values those may have + at any given time), he is also the one to talk to about + it + + + + + &a.steve; + + + Steve is unofficial maintainer of + /usr/src/bin. If you have something + significant you'd like to do there, you should probably + coordinate it first with Steve. He's also Problem + Report-meister, along with &a.phk;. + + + + + &a.brian; + + + Official maintainer of + /usr/bin/ppp and LPD. + + + + + &a.wollman; + + + If you need advice on obscure network internals or + aren't sure of some potential change to the networking + subsystem you have in mind, Garrett is someone to talk + to. + + + + + + + SSH Quick-Start Guide + + + + Update and install the ssh port in + /usr/ports/security/ssh (should be + version 1.2.25 or later). + + + + Make sure that you run &man.ssh-agent.1; before running + other applications. X users, for example, usually do this + from their .xsession or + .xinitrc file. See &man.ssh-agent.1; + for details. + + + + Generate a key pair using &man.ssh-keygen.1;. The key + pair will wind up in the + $HOME/.ssh + directory. + + + + Copy your public key + ($HOME/.ssh/identity.pub) + into your authorized_keys file in your + home directory on freefall + (i.e. + $HOME/.ssh/authorized_keys). + + + + + 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;) so that you won't + have to retype it over and over. + + Test by doing something such as ssh + freefall.FreeBSD.org ls /usr. + + For more information, see + /usr/ports/security/ssh, &man.ssh.1;, + &man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;. + +