swift 05/05/07 19:06:52 Modified: xml/htdocs/proj/en/gdp/doc doc-policy.xml Added: xml/htdocs/proj/en/gdp/doc doc-quiz.xml fix-me.xml.txt Log: Update on GDP policy
Revision Changes Path 1.11 +122 -33 xml/htdocs/proj/en/gdp/doc/doc-policy.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-policy.xml?rev=1.11&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-policy.xml?rev=1.11&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-policy.xml.diff?r1=1.10&r2=1.11&cvsroot=gentoo Index: doc-policy.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v retrieving revision 1.10 retrieving revision 1.11 diff -u -r1.10 -r1.11 --- doc-policy.xml 20 Jan 2005 11:14:51 -0000 1.10 +++ doc-policy.xml 7 May 2005 19:06:52 -0000 1.11 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.10 2005/01/20 11:14:51 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.11 2005/05/07 19:06:52 swift Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> @@ -27,8 +27,8 @@ <license/> -<version>3.10</version> -<date>2005-01-08</date> +<version>3.11</version> +<date>2005-05-07</date> <chapter> <title>Introduction</title> @@ -146,11 +146,12 @@ </p> <p> -Every member of the Gentoo Documentation Project must be subscribed to the +Every member of the Gentoo Documentation Project must be part of the <mail link="[EMAIL PROTECTED]">[EMAIL PROTECTED]</mail> alias. This alias is <e>only</e> used by <uri link="http://bugs.gentoo.org";>bugs.gentoo.org</uri> to inform the documentation -team about bugs regarding the Gentoo Documentation. +team about bugs regarding the Gentoo Documentation. You can add yourself by +editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. </p> <p> @@ -161,8 +162,8 @@ <p> Depending on his responsibilities, he can have limited CVS -access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo -developers. +access to <c>cvs.gentoo.org</c>. Full CVS access can only be given to Gentoo +developers. Read-only CVS access can be given to recruitees. </p> </body> @@ -386,55 +387,143 @@ </body> </section> <section> -<title>Gentoo Documentation Developer</title> +<title>Recruitment Process</title> <body> <p> -As a Gentoo documentation developer should know everything in the <uri -link="/proj/en/devrel/handbook/handbook.xml?part=3&chap=1">Gentoo Ebuild -Policy</uri> even though you're not submitting ebuilds. This is all needed to -ensure our userbase that no Gentoo developer gives wrong information about -critical things. +The Documentation Project has a strict recruitment process outlined below. +This process can not be deviated from in any circumstance. We have opted for +this recruitment process to assure ourselves that the recruitee is well informed +about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven +to be quite effective even though many contributors see it as a too large burden +to cross. </p> <p> -Contact the operational manager of the Gentoo Documentation Project. He -will ask you for your coordinates and other information and then arrange -a mentor for you who will guide you through the first days or weeks as -developer. +This recruitment process is meant only for requests to the Gentoo Documentation +Repository through CVS. Being listed as the maintainer or Point-Of-Contact for a +certain document or range of documents is granted by a simple request to the +Operational Manager or Project Lead. +</p> + +</body> +</section> +<section> +<title>Phase 1: Contributions</title> +<body> + +<p> +No recruitment process starts without investigating the contributions done +already to the Gentoo Documentation Project. The number of contributions must be +large to assure a good knowledge of GuideXML, Coding Style and policy. The +contribution period must be large as well to inform the contributor about the +time-consuming position and pressure the application involves. +</p> + +<p> +The number of contributions and period over which the contributions should be +made depends on the position which the contributor solicits for. Although it is +difficult to write down these measurements in numbers, the following table +should give a general overview. Final decision however lays in the hands of the +Operational Manager. </p> +<table> +<tr> + <th>Position</th> + <th>Minimal Activity</th> + <th>Minimal Period</th> +</tr> +<tr> + <ti>Full-time Developer</ti> + <ti>2 updates per week</ti> + <ti>1 months</ti> +</tr> +<tr> + <ti>Part-time Developer</ti> + <ti>4 updates per month</ti> + <ti>1 months</ti> +</tr> +</table> + <p> -You will be given a Gentoo e-mail address and be appointed to one or -more subprojects. During the initial days or weeks, you should ask your -mentor as much as possible, preferably have him double-check everything -you do. If your function requires CVS access, you will only receive it -when your mentor deems it appropriate. Until then, your mentor is in -charge of the CVS commits. +An update constitutes a non-trivial update to any documentation, translation or +otherwise, completely written by the contributor and committed after review by +any existing documentation developer. The period is fixed - increasing the +contributions does not decrease the period. Also, we don't average the +contributions over time to make sure the contributor doesn't give a contribution +burst and then waits until the Phase is over. +</p> + +<p> +Without this phase we can not know if the contributor understands what it takes +to be a documentation developer. The validation of this activity happens through +bugzilla reports. +</p> + +<p> +Any request for CVS access that does not allow a development activity as written +down in the abovementioned table will not be taken into account. +</p> + +<p> +If you feel that you have shown sufficient amount of contributions, contact +the Operational Manager of the Gentoo Documentation Project. He +will ask you for your coordinates and other information and then arrange +for the next phase to be started. </p> </body> </section> <section> -<title>(Follow-Up) Lead Translator</title> +<title>Phase 2: Read-Only CVS Access</title> <body> <p> -Becoming a (follow-up) lead translator shouldn't be held lightly. You are -responsible for every translated document and final reviewing. The lead -translator will make certain that the translated documents are -grammatically and syntactically perfect. +During phase 2, the recruitee is given read-only access to the Gentoo +Documentation Repository, allowing him to generate commit-ready patches for the +tree. During this period, which is roughly the same as the abovementioned table, +his patches are not edited by a documentation developer anymore, but are either +committed as-is or refused. The recruitee is also assigned to a full-time +documentation developer (the mentor) which will guide him through these last +phases. +</p> + +<p> +The quality of the contributions are in this phase most important - every patch +that does not follow the Documentation Policy, Coding Style or other guideline +that affects the document is refused. </p> <p> -In order to become a Gentoo (follow-up) lead translator you must be a Gentoo -developer. +During this period, you: </p> +<ul> + <li> + are advised to learn about Gentoo's inner workings. + This is required as you will be asked later on to answer Gentoo's <uri + link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>. + </li> + <li> + will be asked to fill in the <uri <<Truncated>> 1.1 xml/htdocs/proj/en/gdp/doc/doc-quiz.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-quiz.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-quiz.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: doc-quiz.xml =================================================================== <?xml version='1.0' encoding="UTF-8"?> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-quiz.xml,v 1.1 2005/05/07 19:06:52 swift Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/proj/en/gdp/doc/doc-quiz.xml"> <title>Gentoo Linux Documentation Policy</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail> </author> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.0 --> <abstract> This document contains the Documentation Project Quiz, a collection of questions pertaining to documentation development which need to be answered correctly before a developer can be given CVS access to the Gentoo Documentation Repository. </abstract> <license/> <version>1.00</version> <date>2005-05-08</date> <chapter> <title>Gentoo Documentation Project Quiz</title> <section> <title>GuideXML Format</title> <body> <p> What is the <c><version></c> element used for? </p> <p> What license does a Gentoo Document use when the <c><license></c> element is set? </p> <p> Where is the content of the <c><abstract></c> element placed on the Gentoo website for a particular guide? And for the Gentoo Handbook? </p> <p> Give the recommended format that you would use for "February 17th, 2005" inside <c><date></c>. What is the benefit for this format? </p> <p> What are the differences between an English document and a translated document XML-wise (not taking into account <path>metadoc.xml</path>)? </p> <p> Suppose you have a document on the differences between distributions. The document has the following chapters and sections. How would you create a link to the section <e>Availability</e>? </p> <pre caption="Document layout"> Chapter: What is a Distribution? Chapter: What are the Differences? Section: Optimization Section: Availability Section: Software Choices Section: Internationalisation Section: Software Maintenance Section: Branding Section: Installation Section: System Configuration Chapter: What is Gentoo? Chapter: Gentoo's Advantages </pre> <p> What is wrong with the following code snippet of a Gentoo Handbook main file which covers "Gentoo Security" in German? Why do you make the changes you made? </p> <pre caption="Excerpt of a handbook main page"> <?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <book lang="de"> <title>Gentoo Sicherheit</title> </pre> <p> What is the result of using the <c>lang</c> attribute? </p> <p> What is a valid GuideXML file and how do you check for validity? </p> </body> </section> <section> <title>Coding Style</title> <body> <p> <uri link="fix-me.xml.txt">On our project page</uri> you will find a link to a GuideXML document that does not validate GuideXML correctly and also isn't written using the Coding Style. Reformat the code so it adheres to the Gentoo Documentation Coding Style and GuideXML format. </p> </body> </section> <section> <title>Commit Policy</title> <body> <p> A new document is submitted through bugzilla. You have succesfully reviewed the document but have not found any issues. What is the procedure for adding it to CVS (give commands and the actions you perform)? </p> <p> A patch for "KaBooZa Guide" has been submitted to bugzilla and you have decided to take care of it even though you know nothing about KaBooZa. How do you proceed? </p> <p> Someone notices a grammar issue on one of Gentoo's pages and reports it on IRC. What do you do if the page is one that you can correct (you have access and you understand the language)? What if you can't correct it? </p> </body> </section> </chapter> </guide> 1.1 xml/htdocs/proj/en/gdp/doc/fix-me.xml.txt file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/fix-me.xml.txt?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/fix-me.xml.txt?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: fix-me.xml.txt =================================================================== <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "dtd/guide.dtd"> <guide link="proj/en/gdp/tests/fix_me.xml"> <title>Gentoo 1.4 Upgrade Guide</title> <author title = "Author"> <mail link = "[EMAIL PROTECTED]">Renée Michù</mail> </author> <author title='editor'><mail link='[EMAIL PROTECTED]'>Gastòn Ledoÿeñ</mail></author> <abstract>A method for upgrading older Gentoo installations in place to Gentoo 1.4</abstract> <version>v0.3</version> <date>October 2, 2004</date> <license/> <chapter> <title>Before you begin</title> <section> <title>Ignore content</title> <body> <p>As mentioned <uri link = "offtopic">later on</uri>, you should not bother about the content of this document. Its sole purpose is to let you show that you can fix a totally broken GuideXML file and apply coding style. If you think it's taking too much of your time then you really need the practice.</p></body></section> <section> <title>General notes</title> <body> <p>Whenever the code listings suggest running the <i>emerge</i> command, it is always a good idea to make a test run of the command using the <i>-p</i> or <i>--pretend</c> option to make sure that the command will do what you expect it to do.</p> </body> </section> </chapter> <chapter> <title>Upgrading in place</title> <section> <title>Get Portage as current as possible</title> <body> <p>Some of the syntax of current ebuilds is unreadable by older versions of Portage. If you don't have at least Portage 2.0.44, try upgrading Portage. <pre> # <c>emerge --sync</c> # <c>emerge -u portage</c> </pre> <note>If your Portage version is very old, you may get an error message containing the phrase "unscriptable object". Read and follow the instructions in <path>/usr/portage/sys-apps/portage/files/README.RESCUE</path>. Your Portage install should then be current.</note></p> You will find more information about Portage in our <uri link="doc/en/handbook/handbook-x86.xml?part=2&chap=1#doc_chap1">Handbook</uri>. </body></section> <section> <title>Preparing GCC for cohabitation</title> <body> <p>You will be installing a newer version of GCC during this upgrade. Versions of GCC older than 2.95.3-r8 are not designed to have multiple versions of GCC installed. You must therefore upgrade GCC to at least version 2.95.3-r8. This will also have the beneficial side-effect of installing the <c>gcc-config</c> package on your system, which can be used to switch back and forth between various installed versions of GCC.</p> <pre> # <i>emerge -u gcc</i> </pre> <p>You can now check to see if gcc-config is working properly:</p> <pre> # <i>gcc-config --get-current-profile</i> </pre> <p>This should return i686-pc-linux-gnu-2.95.3 on most x86 systems. Older systems may return i586-pc-linux-gnu-2.95.3.</p> </body> </section> <section> <title>Installing GCC 3</title> <body> <p> Edit <path>/usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</path> and search for the line containing <c>DEPEND</c>. Remove the <c>glibc</c> dependency and save the ebuild. </p> <pre caption="Editing gcc-3.2.2.ebuild"> # vim /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild </pre> <pre> <codenote>install the latest GCC version on your system:</codenote> # <i>USE="-java" emerge /usr/portage/sys-devel/gcc/gcc-3.2.2.ebuild</i> </pre> </body> </section> <section> <title>Changing profiles</title> <body> <p>Now you need to change two sets of profiles: your gcc-config profile and your Portage profile.</p> <pre> # <i>cd /etc</i> # <i>rm make.profile</i> # <i>ln -s ../usr/portage/profiles/default-x86-1.4 make.profile</i> <comment>(Replace "x86" with your architecture)</comment> </pre> <pre> # <i>gcc-config --list-profiles</i> <comment>(Note the one for the version you just emerged, use it below)</comment> # <i>gcc-config i686-pc-linux-gnu-3.2.2</i> <comment>(Replace with the version you noted above)</comment> </pre> </body> </section> <section id="offtopic"><title>This has nothing to do with the above</title><body><p> During the meeting: <ul> <li>Keep the meeting flowing. This means maintaining focus on the agenda and the objectives of the meeting.</li> <li>Keep the meeting within its allotted time frame (usually one hour)</li> <li>Allow the presentation of an agenda item by the person responsible for that item, before any questions and discussion is undertaken.</li> <li>Get responses from all members before moving onto the next agenda item.</li> <li>Briefly summarize unresolved business. This may include the result of the discussion, specific actions that are to be taken, who's responsible for working on what etc.</li> <li>Allow all attendees to be able to discuss their concerns after the agenda items have been discussed.</li> </ul></p> </chapter> <guide> -- [email protected] mailing list
