Sugar Labs - User contributions [en]

Sugar on a Stick/Documentation SOP

2010-06-15T15:11:48Z

JonSchull: /* Apply your Changes */

Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure SOP] describes how to contribute changes to the documentation.

== Viewing the Documentation ==

You can view a reasonably up-to-date version of the files here:

* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
* [http://mirrors.rit.edu/sugarlabs/soas/docs/creation-kit/index.html Creation Kit]

This is not a permanent location (the URLs above will likely be moving between now and May 2010), and these files may not be completely up-to-date; we are currently obtaining a more permanent infrastructure solution, but the links should suffice at present.

== Contributing Content to the Documentation ==

=== Checking out the latest Version ===

Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>

=== Apply your Changes ===

* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
**For example, Move down to a directory you want to edit, and edit a file with gedit
<pre>cd soas-docs
ls
cd Creation\ Kit/
cd en-US
ls
gedit Book_Info.xml</pre>

* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Make sure to explain your change in Revision_History.xml

=== Generating HTML or PDF output ===

Install publican if you haven't already. On most Linux distributions, this will be:

sudo yum install publican

In the same directory as the file '''''publican.cfg''''' (this will almost certainly be '''''/path/to/soas-docs/Customization Guide''''' or '''''/path/to/soas-docs/Creation Kit'''''), run the following command.

publican build --format=html --lang=en-US

or

publican build --format=pdf --lang=en-US

...depending on what output format you would like. You will see output that looks like this.

<pre>
[you@machine]$ publican build --format=html --lang=en-US
Setting up en-US
Processing file tmp/en-US/xml/Common_Content/Conventions.xml
Processing file tmp/en-US/xml/Common_Content/Feedback.xml
Processing file tmp/en-US/xml/Common_Content/Legal_Notice.xml
<snip more similar stuff>
Beginning work on en-US
Starting html
Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl
Writing pref-Customization_Guide-Preface.html for preface(pref-Customization_Guide-Preface)
Writing sect-Creation_Kit-Preparation-Getting_Started.html for section(sect-Creation_Kit-Preparation-Getting_Started)
Writing chap-Customization_Guide-Preparation.html for chapter(chap-Customization_Guide-Preparation)
<snip more similar stuff>
Writing index.html for book
Finished html
</pre>

When the publican build is finished, you will find your generated docs in a folder called '''''tmp/en-US''''' in your current directory.

=== Create a Patch from your Changes ===

Create a patch using the following command: <pre>git diff > product-name-change.patch</pre>

* ''product'' reflects the folder you made your change in, so either ''creation-kit'' or ''customization-guide''
* ''name'' references to your personal name to track contributions
* ''change'' should be a one or two word description of your proposed change

=== Push your changes ===

==== If you don't have commit access ====

Send an email (with a subject line like this ''[PATCH] name-of-your-patch'') to the SoaS [http://lists.sugarlabs.org/listinfo/soas mailing list] together with your patch and an explanation of what you changed and why you think the change is necessary. Discussion will happen on list.

After that, your patch will be committed and pushed. At some point, you might also be granted access to the GIT repository so that you can commit changes directly without submitting the patches to the list.

==== If you have commit access ====

If you need to apply someone else's patch to the file before committing it, do that first.

patch -p0 < path/file.patch

Once you have applied the patch and otherwise edited the files you want to commit, make the commit.

git commit -a

Leave a commit message describing the change. Finally, push changes back to gitorious with

git push

If you are doing a push for the first time, you may need to specify the origin (this is due to a weird thing in gitorious). In order to do this:

git remote rm origin
git remote add origin gitorious@git.sugarlabs.org:soas-docs/mainline.git
git push origin master

You should be able to simply use <code>git push</code> thereafter.

Sugar on a Stick/Documentation SOP

2010-06-15T15:09:45Z

JonSchull: /* Apply your Changes */

Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure SOP] describes how to contribute changes to the documentation.

== Viewing the Documentation ==

You can view a reasonably up-to-date version of the files here:

* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
* [http://mirrors.rit.edu/sugarlabs/soas/docs/creation-kit/index.html Creation Kit]

This is not a permanent location (the URLs above will likely be moving between now and May 2010), and these files may not be completely up-to-date; we are currently obtaining a more permanent infrastructure solution, but the links should suffice at present.

== Contributing Content to the Documentation ==

=== Checking out the latest Version ===

Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>

=== Apply your Changes ===

* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
**For example, Move down to a directory you want to edit, and edit a file with gEdit
<pre>cd soas-docs
ls
cd Creation\ Kit/
cd en-US
ls
gEdit Book_Info.xml</pre>

* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Make sure to explain your change in Revision_History.xml

=== Generating HTML or PDF output ===

Install publican if you haven't already. On most Linux distributions, this will be:

sudo yum install publican

In the same directory as the file '''''publican.cfg''''' (this will almost certainly be '''''/path/to/soas-docs/Customization Guide''''' or '''''/path/to/soas-docs/Creation Kit'''''), run the following command.

publican build --format=html --lang=en-US

or

publican build --format=pdf --lang=en-US

...depending on what output format you would like. You will see output that looks like this.

<pre>
[you@machine]$ publican build --format=html --lang=en-US
Setting up en-US
Processing file tmp/en-US/xml/Common_Content/Conventions.xml
Processing file tmp/en-US/xml/Common_Content/Feedback.xml
Processing file tmp/en-US/xml/Common_Content/Legal_Notice.xml
<snip more similar stuff>
Beginning work on en-US
Starting html
Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl
Writing pref-Customization_Guide-Preface.html for preface(pref-Customization_Guide-Preface)
Writing sect-Creation_Kit-Preparation-Getting_Started.html for section(sect-Creation_Kit-Preparation-Getting_Started)
Writing chap-Customization_Guide-Preparation.html for chapter(chap-Customization_Guide-Preparation)
<snip more similar stuff>
Writing index.html for book
Finished html
</pre>

When the publican build is finished, you will find your generated docs in a folder called '''''tmp/en-US''''' in your current directory.

=== Create a Patch from your Changes ===

Create a patch using the following command: <pre>git diff > product-name-change.patch</pre>

* ''product'' reflects the folder you made your change in, so either ''creation-kit'' or ''customization-guide''
* ''name'' references to your personal name to track contributions
* ''change'' should be a one or two word description of your proposed change

=== Push your changes ===

==== If you don't have commit access ====

Send an email (with a subject line like this ''[PATCH] name-of-your-patch'') to the SoaS [http://lists.sugarlabs.org/listinfo/soas mailing list] together with your patch and an explanation of what you changed and why you think the change is necessary. Discussion will happen on list.

After that, your patch will be committed and pushed. At some point, you might also be granted access to the GIT repository so that you can commit changes directly without submitting the patches to the list.

==== If you have commit access ====

If you need to apply someone else's patch to the file before committing it, do that first.

patch -p0 < path/file.patch

Once you have applied the patch and otherwise edited the files you want to commit, make the commit.

git commit -a

Leave a commit message describing the change. Finally, push changes back to gitorious with

git push

If you are doing a push for the first time, you may need to specify the origin (this is due to a weird thing in gitorious). In order to do this:

git remote rm origin
git remote add origin gitorious@git.sugarlabs.org:soas-docs/mainline.git
git push origin master

You should be able to simply use <code>git push</code> thereafter.

Sugar on a Stick/Documentation SOP

2010-06-15T15:08:43Z

JonSchull: /* Checking out the latest Version */

Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure SOP] describes how to contribute changes to the documentation.

== Viewing the Documentation ==

You can view a reasonably up-to-date version of the files here:

* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
* [http://mirrors.rit.edu/sugarlabs/soas/docs/creation-kit/index.html Creation Kit]

This is not a permanent location (the URLs above will likely be moving between now and May 2010), and these files may not be completely up-to-date; we are currently obtaining a more permanent infrastructure solution, but the links should suffice at present.

== Contributing Content to the Documentation ==

=== Checking out the latest Version ===

Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>

=== Apply your Changes ===

* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Make sure to explain your change in Revision_History.xml

=== Generating HTML or PDF output ===

Install publican if you haven't already. On most Linux distributions, this will be:

sudo yum install publican

In the same directory as the file '''''publican.cfg''''' (this will almost certainly be '''''/path/to/soas-docs/Customization Guide''''' or '''''/path/to/soas-docs/Creation Kit'''''), run the following command.

publican build --format=html --lang=en-US

or

publican build --format=pdf --lang=en-US

...depending on what output format you would like. You will see output that looks like this.

<pre>
[you@machine]$ publican build --format=html --lang=en-US
Setting up en-US
Processing file tmp/en-US/xml/Common_Content/Conventions.xml
Processing file tmp/en-US/xml/Common_Content/Feedback.xml
Processing file tmp/en-US/xml/Common_Content/Legal_Notice.xml
<snip more similar stuff>
Beginning work on en-US
Starting html
Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl
Writing pref-Customization_Guide-Preface.html for preface(pref-Customization_Guide-Preface)
Writing sect-Creation_Kit-Preparation-Getting_Started.html for section(sect-Creation_Kit-Preparation-Getting_Started)
Writing chap-Customization_Guide-Preparation.html for chapter(chap-Customization_Guide-Preparation)
<snip more similar stuff>
Writing index.html for book
Finished html
</pre>

When the publican build is finished, you will find your generated docs in a folder called '''''tmp/en-US''''' in your current directory.

=== Create a Patch from your Changes ===

Create a patch using the following command: <pre>git diff > product-name-change.patch</pre>

* ''product'' reflects the folder you made your change in, so either ''creation-kit'' or ''customization-guide''
* ''name'' references to your personal name to track contributions
* ''change'' should be a one or two word description of your proposed change

=== Push your changes ===

==== If you don't have commit access ====

Send an email (with a subject line like this ''[PATCH] name-of-your-patch'') to the SoaS [http://lists.sugarlabs.org/listinfo/soas mailing list] together with your patch and an explanation of what you changed and why you think the change is necessary. Discussion will happen on list.

After that, your patch will be committed and pushed. At some point, you might also be granted access to the GIT repository so that you can commit changes directly without submitting the patches to the list.

==== If you have commit access ====

If you need to apply someone else's patch to the file before committing it, do that first.

patch -p0 < path/file.patch

Once you have applied the patch and otherwise edited the files you want to commit, make the commit.

git commit -a

Leave a commit message describing the change. Finally, push changes back to gitorious with

git push

If you are doing a push for the first time, you may need to specify the origin (this is due to a weird thing in gitorious). In order to do this:

git remote rm origin
git remote add origin gitorious@git.sugarlabs.org:soas-docs/mainline.git
git push origin master

You should be able to simply use <code>git push</code> thereafter.

Sugar on a Stick/Documentation SOP

2010-06-15T15:08:23Z

JonSchull: /* Checking out the latest Version */

Starting with the upcoming SoaS version (release date: ''2010-05-11''), a good amount of the related documentation will be created through [https://fedorahosted.org/publican/ publican]. This [http://en.wikipedia.org/wiki/Standard_operating_procedure SOP] describes how to contribute changes to the documentation.

== Viewing the Documentation ==

You can view a reasonably up-to-date version of the files here:

* [http://mirrors.rit.edu/sugarlabs/soas/docs/customization-guide/index.html Customization Guide]
* [http://mirrors.rit.edu/sugarlabs/soas/docs/creation-kit/index.html Creation Kit]

This is not a permanent location (the URLs above will likely be moving between now and May 2010), and these files may not be completely up-to-date; we are currently obtaining a more permanent infrastructure solution, but the links should suffice at present.

== Contributing Content to the Documentation ==

=== Checking out the latest Version ===

Clone the GIT repository with the Sugar on a Stick documentation from GIT by running:
<pre>git clone git://git.sugarlabs.org/soas-docs/mainline.git soas-docs</pre>

Move down to a directory you want to edit, and edit a file with gEdit
<pre>cd soas-docs
ls
cd Creation\ Kit/
cd en-US
ls
gEdit Book_Info.xml</pre>

=== Apply your Changes ===

* Edit away! - Try to follow these conventions [https://fedorahosted.org/publican/browser/trunk/publican/datadir/Common_Content/common/en-US/Conventions.xml here].
* Bump the edition tag in ''Book_Info.xml'' after a major change.
* Make sure to explain your change in Revision_History.xml

=== Generating HTML or PDF output ===

Install publican if you haven't already. On most Linux distributions, this will be:

sudo yum install publican

In the same directory as the file '''''publican.cfg''''' (this will almost certainly be '''''/path/to/soas-docs/Customization Guide''''' or '''''/path/to/soas-docs/Creation Kit'''''), run the following command.

publican build --format=html --lang=en-US

or

publican build --format=pdf --lang=en-US

...depending on what output format you would like. You will see output that looks like this.

<pre>
[you@machine]$ publican build --format=html --lang=en-US
Setting up en-US
Processing file tmp/en-US/xml/Common_Content/Conventions.xml
Processing file tmp/en-US/xml/Common_Content/Feedback.xml
Processing file tmp/en-US/xml/Common_Content/Legal_Notice.xml
<snip more similar stuff>
Beginning work on en-US
Starting html
Using XML::LibXSLT on /usr/share/publican/xsl/html.xsl
Writing pref-Customization_Guide-Preface.html for preface(pref-Customization_Guide-Preface)
Writing sect-Creation_Kit-Preparation-Getting_Started.html for section(sect-Creation_Kit-Preparation-Getting_Started)
Writing chap-Customization_Guide-Preparation.html for chapter(chap-Customization_Guide-Preparation)
<snip more similar stuff>
Writing index.html for book
Finished html
</pre>

When the publican build is finished, you will find your generated docs in a folder called '''''tmp/en-US''''' in your current directory.

=== Create a Patch from your Changes ===

Create a patch using the following command: <pre>git diff > product-name-change.patch</pre>

* ''product'' reflects the folder you made your change in, so either ''creation-kit'' or ''customization-guide''
* ''name'' references to your personal name to track contributions
* ''change'' should be a one or two word description of your proposed change

=== Push your changes ===

==== If you don't have commit access ====

Send an email (with a subject line like this ''[PATCH] name-of-your-patch'') to the SoaS [http://lists.sugarlabs.org/listinfo/soas mailing list] together with your patch and an explanation of what you changed and why you think the change is necessary. Discussion will happen on list.

After that, your patch will be committed and pushed. At some point, you might also be granted access to the GIT repository so that you can commit changes directly without submitting the patches to the list.

==== If you have commit access ====

If you need to apply someone else's patch to the file before committing it, do that first.

patch -p0 < path/file.patch

Once you have applied the patch and otherwise edited the files you want to commit, make the commit.

git commit -a

Leave a commit message describing the change. Finally, push changes back to gitorious with

git push

If you are doing a push for the first time, you may need to specify the origin (this is due to a weird thing in gitorious). In order to do this:

git remote rm origin
git remote add origin gitorious@git.sugarlabs.org:soas-docs/mainline.git
git push origin master

You should be able to simply use <code>git push</code> thereafter.