From Fedora Project Wiki

No edit summary
 
(33 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The term ''guide'' here refers to any piece of formal Fedora documentation published by the [[Fedora Documentation Project]] and published on http://docs.fedoraproject.org. Guides range from detailed manuals hundreds of pages long to short articles that describe specific tasks such as how to burn a DVD from an ISO file.
The term ''guide'' here refers to any piece of formal Fedora documentation maintained by the [[Fedora Documentation Project]] and published on http://docs.fedoraproject.org. Guides range from detailed manuals hundreds of pages long to short articles that describe specific tasks such as how to burn a DVD from an ISO file.
 
Your guide might be an entirely new piece of writing or a project that you are migrating to Fedora from elsewhere, for example, a Red Hat Enterprise Linux document that you are bringing upstream into Fedora. These instructions apply in either case.
 
==Prerequisites==
Before you follow this procedure, you must
* be a member of the Fedora Project (and therefore have an identity in the Fedora Account System (FAS)) — [https://admin.fedoraproject.org/accounts/user/new join the Fedora Project] (be sure to sign the CLA in the account system too)
* be a member of the docs-writers group — [https://admin.fedoraproject.org/accounts/group/view/docs-writers apply]
* have '''Git''' installed on your system. — yum install git
* have '''Publican''' and the Fedora brand package for '''Publican''' installed on your system. — yum install publican publican-fedora


==Apply to have your document hosted on fedorahosted.org==
==Apply to have your document hosted on fedorahosted.org==


File a ticket to request hosting from the Fedora Infrastructure team: https://hosted.fedoraproject.org/fedora-infrastructure/newticket
<ol><li>Visit the Fedora Infrastructure Trac at https://fedorahosted.org/fedora-infrastructure/</li>
<li>Click the '''Login''' link near the top right of the screen and supply your FAS username and password when prompted.</li>
<li>Click the '''New Ticket''' link near the top right of the screen.</li>
<li>Fill in the '''Short Summary''' field with:
<pre>Hosting request for NAME_OF_YOUR_GUIDE</pre></li>
<li>Select '''Hosting Request''' in the  '''Type''' drop-down menu.</li>
<li>A dialog box opens and asks you whether to '''Apply template by ticket type?'''. Click '''No'''.</li>
<li>Copy and paste the following information into the main text box, replacing any content already there:
<pre>Project name: docs/name-of-your-guide
 
Project short summary: SUMMARY_OF_YOUR_GUIDE
 
SCM choice (git/bzr/hg/svn): git


You can find instructions for filling out the ticket here: https://fedorahosted.org/web/new
Project admin Fedora Account System account name: YOUR_FAS_USERNAME


Note also:
Yes/No, would you like a Trac instance for your project?: Yes


    * Git is the preferred SCM for Fedora Documentation
Do you need a mailing list? No
    * By convention, documentation Git repos are prefaced with docs/, so request docs/Your_Guide.git as the Project Name in the ticket.
    * It's a good idea to recommend a Trac instance so that you can publish some basic details of your project. For example: https://fedorahosted.org/install-guide/


==Add your guide to the Docs Project guides table==
Send commits to the following list: docs-commits@lists.fedorahosted.org


When you have some hosting space and have checked in your source code, add your details and details of your guide to the guides table in the Fedora wiki: https://fedoraproject.org/wiki/Docs_Project_guides_table#Guides
NOTE: No separate commit group needed. Please give commit access to the docs-writers group.
</pre>
{{admon/important|Provide the name of your guide in the '''Project name''' field in the following format:
* lower case letters only
* separate words with a hyphen
* preface the title with '''docs/'''
* do not include '''fedora''' in the name of your guide.
For example, if your guide is the '''Fedora Configuration Guide''', provide this as:  
<code>Project name:docs/configuration-guide</code>.}}</li>
<li>Select '''Minor''' in the  '''Priority''' drop-down menu.</li>
<li>Select '''Hosted Projects''' in the  '''Component''' drop-down menu.</li>
<li>Click the '''Submit ticket''' button.</li></ol>


==Add your guide to Transifex==
You will receive a notification by email when the Fedora Infrastructure Team has created space for your project.


Transifex is the Fedora Project's translation interface.
==Create local and remote repositories for your guide==
When the Fedora Infrastructure Team notifies you that your hosting space is ready, create the local and remote git repositories for your guide.
<ol><li>Open a virtual console or terminal emulator and change into a convenient directory in which to store your local copy of the source code.</li>
<li>Check out the remote repository. Run:
<pre>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/NAME_OF_GUIDE.git
</pre>
Where '''USERNAME''' is your FAS username, and '''NAME_OF_GUIDE''' is the name of your guide.  


If you have a stable version of your guide, create a separate branch in which translators can work. This branch is named after the branch of Fedora for which the documentation is to be released. The master branch of your document is used only for developing the English text and should not contain POT or PO files. The process for branching a Fedora document for translation is outlined on the Fedora wiki: https://fedoraproject.org/wiki/Branching_a_document_in_git
Git clones the remote repository into a new directory with the same name as the name of your guide. Because the repository is currently empty, Git warns you:
<pre>warning: You appear to have cloned an empty repository.</pre>
Ignore this warning. </li>
<li>Change into the new directory.</li>
<li>Add the files for your guide:
<ul>
<li>If you are creating a new guide, create the structure of the guide with '''Publican''':
<pre>publican create --name NAME_OF_GUIDE</pre>
This will create a new directory, NAME_OF_GUIDE. You may wish to use the top level of the git repo as the top level of the guide, ie
<pre>mv NAME_OF_GUIDE/* ./;rmdir NAME_OF_GUIDE</pre>
</li>
<li>
Refer to the [http://jfearn.fedorapeople.org/en-US/Publican/ ''Publican User Guide''] for instructions on setting up a new document with '''Publican'''</li>
<li>If you are moving an existing project into Fedora, copy or move the files into this new directory. If the project was previously in a version-control system, be careful not to copy hidden directories such as .svn or .git directories. If the project was previously maintained in SVN or CVS and has multiple branches, only import the trunk at this stage. Import separate branches of the project into separate Git branches later, using the procedure described in [[Branching a document in git]]</li>
</ul></li>
<li>When you have created or imported your source files, initialize the local git repository. In the directory created earlier by the '''git clone''' command, run:
<pre>git init</pre></li>
<li>Now check the files into the remote repository. In the directory created earlier by the '''git clone''' command, run:
<pre>git add .
git commit -m"Initial check-in"
git push origin master</pre></li>
</li>
</ol>


The translation branch should contain the Publican pot directory and any language directories that you are importing. You should also run publican update_po to add a few other languages heavily translated in Fedora, including nl-NL (Dutch), pl-PL (Polish), pt-PT (Portuguese), sv-SE (Swedish), and uk-UA (Ukrainian).
==Request a Bugzilla component for your guide==
All guides share the same ''product'' in Bugzilla: '''Fedora Documentation''', and each one has a separate ''component''. This is the component against which readers will file bugs and suggestions for improvement.


When you have created the translation branch, follow the instructions on the Fedora wiki to request the Fedora Localization Team to add it to Transifex: https://fedoraproject.org/wiki/L10N/FAQ#How_do_I_add_a_module_to_Transifex.3F_.28.23add-transifex.29
<ol><li>Open a bug in Bugzilla against the '''docs-requests''' component in the '''Fedora Documentation''' product ([https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora%20Documentation&component=docs-requests link])</li>
<li>Use the words '''New Bugzilla component''' in the '''Summary''' field, for example, '''New Bugzilla component for Fedora Astronomy Guide'''</li>
<li>When the new component is created, the bug will be updated with its details. Bugzilla components for Fedora documentation usually take the form of the title of the book in lower case, with words separated by dashes. For example: ''astronomy-guide''</li>
<li>When you know the name of your Bugzilla component, be sure to update the '''BOOKID''' entity in the entity file of your book. For example:
<pre><!ENTITY BOOKID "astronomy-guide"></pre></li>
</ol>


If your guide is still under development, you do not need to create a branch for translations yet. Wait until you finalise the English content first.
==Add your guide to the Docs Project guides table==


==Publish your guide on docs.fedoraproject.org==
When you have checked in your source code, add your details and details of your guide to the guides table in the Fedora wiki: https://fedoraproject.org/wiki/Docs_Project_guides_table#Guides


Check out the git repo that holds the content of the docs.fedoraproject.org website:


<pre>ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</pre>


Build your book in Publican, then insert it into a logical place in the directory structure. Edit the top-level index.html file to link to your book in the formats and languages in which it is available.


This process is currently (May 2010) undergoing changes to accommodate the new web publishing features coming in Publican 2.0.


[[Category:Docs Project process]]
[[Category:Docs Project process]]
[[Category:How to]]
[[Category:Docs Project]]

Latest revision as of 20:46, 21 March 2014

The term guide here refers to any piece of formal Fedora documentation maintained by the Fedora Documentation Project and published on http://docs.fedoraproject.org. Guides range from detailed manuals hundreds of pages long to short articles that describe specific tasks such as how to burn a DVD from an ISO file.

Your guide might be an entirely new piece of writing or a project that you are migrating to Fedora from elsewhere, for example, a Red Hat Enterprise Linux document that you are bringing upstream into Fedora. These instructions apply in either case.

Prerequisites

Before you follow this procedure, you must

  • be a member of the Fedora Project (and therefore have an identity in the Fedora Account System (FAS)) — join the Fedora Project (be sure to sign the CLA in the account system too)
  • be a member of the docs-writers group — apply
  • have Git installed on your system. — yum install git
  • have Publican and the Fedora brand package for Publican installed on your system. — yum install publican publican-fedora

Apply to have your document hosted on fedorahosted.org

  1. Visit the Fedora Infrastructure Trac at https://fedorahosted.org/fedora-infrastructure/
  2. Click the Login link near the top right of the screen and supply your FAS username and password when prompted.
  3. Click the New Ticket link near the top right of the screen.
  4. Fill in the Short Summary field with:
    Hosting request for NAME_OF_YOUR_GUIDE
  5. Select Hosting Request in the Type drop-down menu.
  6. A dialog box opens and asks you whether to Apply template by ticket type?. Click No.
  7. Copy and paste the following information into the main text box, replacing any content already there:
    Project name: docs/name-of-your-guide
    
    Project short summary: SUMMARY_OF_YOUR_GUIDE
    
    SCM choice (git/bzr/hg/svn): git
    
    Project admin Fedora Account System account name: YOUR_FAS_USERNAME
    
    Yes/No, would you like a Trac instance for your project?: Yes
    
    Do you need a mailing list? No
    
    Send commits to the following list: docs-commits@lists.fedorahosted.org
    
    NOTE: No separate commit group needed. Please give commit access to the docs-writers group.
    
    Provide the name of your guide in the Project name field in the following format:
    • lower case letters only
    • separate words with a hyphen
    • preface the title with docs/
    • do not include fedora in the name of your guide.

    For example, if your guide is the Fedora Configuration Guide, provide this as:

    Project name:docs/configuration-guide.
  8. Select Minor in the Priority drop-down menu.
  9. Select Hosted Projects in the Component drop-down menu.
  10. Click the Submit ticket button.

You will receive a notification by email when the Fedora Infrastructure Team has created space for your project.

Create local and remote repositories for your guide

When the Fedora Infrastructure Team notifies you that your hosting space is ready, create the local and remote git repositories for your guide.

  1. Open a virtual console or terminal emulator and change into a convenient directory in which to store your local copy of the source code.
  2. Check out the remote repository. Run:
    git clone ssh://USERNAME@git.fedorahosted.org/git/docs/NAME_OF_GUIDE.git
    

    Where USERNAME is your FAS username, and NAME_OF_GUIDE is the name of your guide.

    Git clones the remote repository into a new directory with the same name as the name of your guide. Because the repository is currently empty, Git warns you:

    warning: You appear to have cloned an empty repository.
    Ignore this warning.
  3. Change into the new directory.
  4. Add the files for your guide:
    • If you are creating a new guide, create the structure of the guide with Publican:
      publican create --name NAME_OF_GUIDE

      This will create a new directory, NAME_OF_GUIDE. You may wish to use the top level of the git repo as the top level of the guide, ie

      mv NAME_OF_GUIDE/* ./;rmdir NAME_OF_GUIDE
    • Refer to the Publican User Guide for instructions on setting up a new document with Publican
    • If you are moving an existing project into Fedora, copy or move the files into this new directory. If the project was previously in a version-control system, be careful not to copy hidden directories such as .svn or .git directories. If the project was previously maintained in SVN or CVS and has multiple branches, only import the trunk at this stage. Import separate branches of the project into separate Git branches later, using the procedure described in Branching a document in git
  5. When you have created or imported your source files, initialize the local git repository. In the directory created earlier by the git clone command, run:
    git init
  6. Now check the files into the remote repository. In the directory created earlier by the git clone command, run:
    git add .
    git commit -m"Initial check-in"
    git push origin master

Request a Bugzilla component for your guide

All guides share the same product in Bugzilla: Fedora Documentation, and each one has a separate component. This is the component against which readers will file bugs and suggestions for improvement.

  1. Open a bug in Bugzilla against the docs-requests component in the Fedora Documentation product (link)
  2. Use the words New Bugzilla component in the Summary field, for example, New Bugzilla component for Fedora Astronomy Guide
  3. When the new component is created, the bug will be updated with its details. Bugzilla components for Fedora documentation usually take the form of the title of the book in lower case, with words separated by dashes. For example: astronomy-guide
  4. When you know the name of your Bugzilla component, be sure to update the BOOKID entity in the entity file of your book. For example:
    <!ENTITY BOOKID "astronomy-guide">

Add your guide to the Docs Project guides table

When you have checked in your source code, add your details and details of your guide to the guides table in the Fedora wiki: https://fedoraproject.org/wiki/Docs_Project_guides_table#Guides