diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml index e4b2388eac..b008e09c42 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml @@ -1,436 +1,441 @@ %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 Main Repository Host freefall.FreeBSD.org International Crypto Repository Host internat.FreeBSD.org Login Methods &man.ssh.1; Main CVSROOT /home/ncvs International Crypto CVSROOT /home/cvs.crypt Main CVS Repository Meisters &a.jdp; and &a.peter; as well as &a.asami; for ports/ International Crypto CVS Repository Meister &a.markm; 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 . + It is required that you use &man.ssh.1; or &man.telnet.1; + and Kerberos 5 to connect to the repository hosts. These are + generally more secure than plain &man.telnet.1; or + &man.rlogin.1; since credential negotiation will always be + encrypted. All traffic is encrypted by default with &man.ssh.1;. + With utilities like &man.ssh-agent.1; and &man.scp.1; also + available, &man.ssh.1; 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. Satoshi Asami is also a repomeister for the ports/ portion of the - tree. + tree. Mark Murray is the repomeister for the International + Crypto Repository in South Africa. 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 over any modifications to the ports collection or ports make macro files. He is also the one responsible for administering code freezes before the releases. &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.markm; Mark is the CVS repository meister for the international cypto repository kept on - internat.FreeBSD.org. + internat.FreeBSD.org in South Africa. + Mark also oversees most of the crypto code; if you have + any crypto updates, please ask Mark first. &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/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml index e4b2388eac..b008e09c42 100644 --- a/en_US.ISO_8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO_8859-1/articles/committers-guide/article.sgml @@ -1,436 +1,441 @@ %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 Main Repository Host freefall.FreeBSD.org International Crypto Repository Host internat.FreeBSD.org Login Methods &man.ssh.1; Main CVSROOT /home/ncvs International Crypto CVSROOT /home/cvs.crypt Main CVS Repository Meisters &a.jdp; and &a.peter; as well as &a.asami; for ports/ International Crypto CVS Repository Meister &a.markm; 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 . + It is required that you use &man.ssh.1; or &man.telnet.1; + and Kerberos 5 to connect to the repository hosts. These are + generally more secure than plain &man.telnet.1; or + &man.rlogin.1; since credential negotiation will always be + encrypted. All traffic is encrypted by default with &man.ssh.1;. + With utilities like &man.ssh-agent.1; and &man.scp.1; also + available, &man.ssh.1; 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. Satoshi Asami is also a repomeister for the ports/ portion of the - tree. + tree. Mark Murray is the repomeister for the International + Crypto Repository in South Africa. 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 over any modifications to the ports collection or ports make macro files. He is also the one responsible for administering code freezes before the releases. &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.markm; Mark is the CVS repository meister for the international cypto repository kept on - internat.FreeBSD.org. + internat.FreeBSD.org in South Africa. + Mark also oversees most of the crypto code; if you have + any crypto updates, please ask Mark first. &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;.