XS Community Edition/0.4/Hacking: Difference between revisions

From OLPC
Jump to navigation Jump to search
(remove http (invalid ssl cert), add --depth=1 to reduce download cost)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{xsce}}
==The Code==
=The Code=


===Downloading code===
==Downloading code==


'''$ git clone http://dev.sugardextrose.org/xs-config'''
<code>$ git clone --depth=1 git://dev.sugardextrose.org/xs-config</code> <-- (Shows progress through git:// protocol)

'''$ git clone git://dev.sugardextrose.org/xs-config''' <-- (Shows progress through git:// protocol)


or for commit access (requires login and password)
or for commit access (requires login and password)


'''$ git clone http://dev.sugardextrose.org/git/xs-config'''
<code>$ git clone http://dev.sugardextrose.org/git/xs-config</code>


===Code layout===
==Code layout==


The 0.3 revision of XSCE software has been made more modular.
The 0.3 revision of XSCE software has been made more modular.


Configuration consists of a series of scripts in the plugins.d tree. Major services are separated under plugins.d. The layout of each plugin is described in http://schoolserver.wordpress.com/xs-installation/add-a-service-to-school-server-by-creating-a-plugin/.
Configuration consists of a series of scripts in the plugins.d tree. Major services are separated under plugins.d. The layout of each plugin is described in http://schoolserver.wordpress.com/xs-installation/add-a-service-to-school-server-by-creating-a-plugin/.



In the 0.2 release, the code lived in the xs-config/ dir. Consider these 3 subdirectories of xs-config:
In the 0.2 release, the code lived in the xs-config/ dir. Consider these 3 subdirectories of xs-config:


#<code>scripts/</code>
<ol>


<li><code>scripts/</code>
<br>
Configuration consists of a series of scripts which live in the scripts/ dir. The process is kicked off by running xs-setup. xs-setup calls a series of scripts with the naming convention the xs-[ServiceName] each of which set up an individual service.
Configuration consists of a series of scripts which live in the scripts/ dir. The process is kicked off by running xs-setup. xs-setup calls a series of scripts with the naming convention the xs-[ServiceName] each of which set up an individual service.


<li><code>cfg/etc/</code>
#<code>cfg/etc/</code>

<br>
When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.
When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.


<li><code>cfg/html/top/</code>
#<code>cfg/html/top/</code>

<br>
The web based GUI is located under cfg/html/top/
The web based GUI is located under cfg/html/top/


=Building=
</ol>
<code>$ make rpm</code>

=Design=

[http://schoolserver.wordpress.com/xs-installation/add-a-service-to-school-server-by-creating-a-plugin/ Add a Service to School Server by Creating a Plugin] (original written April 2013).

Older Design documents:
[https://docs.google.com/document/pub?id=1dnhU2F6EntepVXTgN8QpkME8fZVUuPjcCoMUfAVKbcc Design Document],
[[User:Holt/XS_Community_Edition/Use_Cases | Use cases]], and
[https://docs.google.com/spreadsheet/ccc?key=0Aki16JhXo4mEdEU1MzA5OGJuOERtbGxHSkxzT2ZFSGc Release Priorities].

Original OLPC XS design and implementation available at [[School Server|OLPC School Server]].

=XSCE Git Branch Model=

==Main Branch==
The main branch in this model is origin/master. The source code of HEAD always reflects the state of development for the next release. This can be called the “integration branch.” Commits to this branch trigger automatic builds.

==Supporting Branches==
In addition to the master, branch there are three types of supporting branches to aid parallel development between team members, ease tracking of features, prepare for releases and to assist in quickly fixing release issues.

The three types of branches we use are:
* Feature branches
* Testing branches
* Release branches

===Feature Branches===
Must branch off from: master

Must merge back into: master

Branch naming convention: anything except master or release-*

Feature branches (or topic branches) are used to develop new features for the future releases. When starting development of a feature, the target release for this release may not be known. A feature branch only exists as long as the feature is in development.

It will either be merged back into master (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).

Feature branches typically exist only in developer repos, not in origin.

===Testing Branches===
Must branch off from: master

Must merge back into: master

Branch naming convention: testing-*

A new testing branched from master when the Release Manager declares the first release candidate ready. Most features that are targeted for the release should be merged into master at this point in time.

Periodically the release manager manually triggers a new release candidate build from testing .

===Release Branches===
Must branch off from: testing-*


Must merge back into: none
===Building===
'''$ make rpm'''


Branch naming convention: release-*
==Design and architecture==


A new release is branched from testing when the Release Manager declares the release ready. All features that are targeted for the release must be merged in to develop at this point in time. All features targeted at future releases may not—they must wait until after the release branch is branched off.
The school server is a collection of common network related services which can be installed and configured as necessary. The School Server provides a core base of services on which extended service can be installed and modified and modified as modules.


The initial commit to release results in a release. Commits to release trigger automatic builds


====Web server (apache)====
===Hotfix Branches===
After final release the testing branch becomes the hotfix branch.
A web server enables the school server to generate and deliver web pages at the request of client Laptop. The web server is a building block for many other extended services.


Hotfix branches support a specific release. They enable minor bug fixes to a release which can also be merged back to master. By doing this work on a hotfix branch, it is clear that this is a minor bugfix which is designed to fix a specific issue in a release.
====Proxy server and web cache (squid)====


Subsequent commits to testing result in point releases.
A proxy server and web cache reduces the overall bandwidth needs of the school. All Laptops requests pass through the proxy and are temporarily stored. If more than one student requests the same file, the proxy only has to go out to the public internet once.


=Git Workflow=
====OLPC-update (rsync)====
==Creating a feature branch==
When starting work on a new feature, branch off from the master branch.


<code>$ git checkout -b myfeature master</code>
OLPC-update is necessary to update the kernel of XO due to modifications that have been made to the kernel which prevent standard package management systems from working correctly.


Switched to a new branch "myfeature"
====Activity update (activity updater)====


==Incorporating a finished feature on master==
The activity updater enables teachers to easily distribute new or updated activities to their students.
Finished features may be merged into the master branch to prepare them for inclusion in the upcoming release:


<code>$ git checkout master</code>
====Virtual Private Network (open vpn)====


Switched to branch 'master'
The Virtual private Network is useful for creating secure point-to-point connections in routed or bridged configurations which makes is possible for remote access facilities.


<code>$ git merge myfeature</code>
==Hacking==
===Core Services===
===Dynamic Host Configuration Protocol (dhcpd)===


Updating ea1b82a..05e9557
DHCP (Dynamic Host Configuration Protocol) allows the school server to assign IP addresses to connected XOs. DHCP is a network protocol used to configure network devices so that they can connect and communicate over an IP network.
(Summary of changes)


<code>$ git branch -d myfeature</code>
Project Link http://www.isc.org/software/dhcp


Deleted branch myfeature (was 05e9557).
===Internet Domain Name Server (named)===


<code>$ git push origin master</code>
The Domain Name System (DNS) converts the name of a Web site (www.google.com) to an IP address (65.115.71.34). Named is a daemon within BIND that responds to DNS queries from remote machines.


==Creating a testing branch==
Project Link https://www.isc.org/software/bind
Only the release manager should create a testing branch from the master branch when the state of master is ready for community testing. He creates the testing branch and gives it a name reflecting the new version number:


<code>$ git checkout -b testing-0.3 master</code>
===Network Address Translation/NAT, Gateway, IP Masquerading, Firewall (iptables)===


Switched to a new branch "testing-0.3"
NAT. The School Server used Network Address Translation to provide security, privacy, and scalability. NAT enables all of the XOs within a school to appear to the world as a single machine. As a security measure all packets pass through the server. This can be further augmented by additional filtering. Privacy in enhance because students machines are not directly accessible from the public internet. Finally NAT enhances scalability as an entire school only needs a single IP address.


<code>$ git tag -a 0.3</code>
Project Link http://www.netfilter.org/projects/iptables/


After creating a new branch and switching to it, he tags it with the version number.
===XMPP server (ejabberd)===


==Creating a release branch==
Extensible Messaging and Presence Protocol (XMPP)is a communications protocol for near real-time, instant messaging (IM), presence information, and contact list maintenance. In the classroom environment it's used to give support to XO Collaboration features through Gabble.
Only the release manager should create a release branch from the testing branch when the state of testing is ready for the “next release.” He creates the release branch and gives it a name reflecting the new version number:


<code>$ git checkout -b release-0.3 testing-0.3</code>
Project Link http://www.ejabberd.im/


Switched to a new branch "release-0.3"
===IDMGR The Identity Manager is a service which accepts requests for registration from laptops [[School_Identity_Manager]]===


<code>$ git tag -a 0.3</code>
Project Link http://wiki.laptop.org/go/School_Identity_Manager


After creating a new branch and switching to it, he tags it with the version number.
===Web server (apache)===


==Creating a hotfix branch==
A web server enables the school server to generate and deliver web pages at the request of client Laptop. The web server is a building block for many other extended services.
After a release the testing branch becomes the hotfix branch


==Incorporating a hotfix to a release==
Project Link http://www.apache.org/
After testing, finished hotfixes may be merged into the release-* branch to prepare them for inclusion in the next point release:


<code>$ git checkout release-0.3</code>
===Proxy server and web cache (squid)===


Switched to branch 'release-0.3'
A proxy server and web cache reduces the overall bandwidth needs of the school. All Laptops requests pass through the proxy and are temporarily stored. If more than one student requests the same file, the proxy only has to go out to the public internet once.


<code>$ git merge testing-0.3</code>
Project Link http://www.squid-cache.org/


Updating ea1b82a..05e9557
===OLPC-update (rsync)===
(Summary of changes)


<code>$ git tag -a 0.3.1</code>
OLPC-update is necessary to update the kernel of XO due to modifications that have been made to the kernel which prevent standard package management systems from working correctly.


<code>$ git push origin release-0.3</code>
Project Link http://wiki.laptop.org/go/Olpc-update


==Incorporating a hotfix to master==
===Activity update (activity updater)===
If necessary, finished hotfixes may be merged into the master branch for inclusion in future releases:


<code>$ git checkout master</code>
The activity updater enables teachers to easily distribute new or updated activities to their students


Switched to branch 'master'
Project Link ???


<code>$ git merge testing</code>
===Virtual Private Network (open vpn)===


Updating ea1b82a..05e9557
The Virtual private Network is useful for creating secure point-to-point connections in routed or bridged configurations which makes is possible for remote access facilities
(Summary of changes)


<code>$ git push origin master</code>
Project Link http://openvpn.net/

Latest revision as of 01:03, 9 September 2013

This IIAB XSCE content does not reflect the opinion of OLPC. These pages were created by members of a volunteer community supporting OLPC and deployments.

The Code

Downloading code

$ git clone --depth=1 git://dev.sugardextrose.org/xs-config <-- (Shows progress through git:// protocol)

or for commit access (requires login and password)

$ git clone http://dev.sugardextrose.org/git/xs-config

Code layout

The 0.3 revision of XSCE software has been made more modular.

Configuration consists of a series of scripts in the plugins.d tree. Major services are separated under plugins.d. The layout of each plugin is described in http://schoolserver.wordpress.com/xs-installation/add-a-service-to-school-server-by-creating-a-plugin/.

In the 0.2 release, the code lived in the xs-config/ dir. Consider these 3 subdirectories of xs-config:

  1. scripts/

Configuration consists of a series of scripts which live in the scripts/ dir. The process is kicked off by running xs-setup. xs-setup calls a series of scripts with the naming convention the xs-[ServiceName] each of which set up an individual service.

  1. cfg/etc/

When necessary, the xs-[ServiceName] scripts installs files from under cfg/etc as necessary.

  1. cfg/html/top/

The web based GUI is located under cfg/html/top/

Building

$ make rpm

Design

Add a Service to School Server by Creating a Plugin (original written April 2013).

Older Design documents: Design Document, Use cases, and Release Priorities.

Original OLPC XS design and implementation available at OLPC School Server.

XSCE Git Branch Model

Main Branch

The main branch in this model is origin/master. The source code of HEAD always reflects the state of development for the next release. This can be called the “integration branch.” Commits to this branch trigger automatic builds.

Supporting Branches

In addition to the master, branch there are three types of supporting branches to aid parallel development between team members, ease tracking of features, prepare for releases and to assist in quickly fixing release issues.

The three types of branches we use are:

  • Feature branches
  • Testing branches
  • Release branches

Feature Branches

Must branch off from: master

Must merge back into: master

Branch naming convention: anything except master or release-*

Feature branches (or topic branches) are used to develop new features for the future releases. When starting development of a feature, the target release for this release may not be known. A feature branch only exists as long as the feature is in development.

It will either be merged back into master (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).

Feature branches typically exist only in developer repos, not in origin.

Testing Branches

Must branch off from: master

Must merge back into: master

Branch naming convention: testing-*

A new testing branched from master when the Release Manager declares the first release candidate ready. Most features that are targeted for the release should be merged into master at this point in time.

Periodically the release manager manually triggers a new release candidate build from testing .

Release Branches

Must branch off from: testing-*

Must merge back into: none

Branch naming convention: release-*

A new release is branched from testing when the Release Manager declares the release ready. All features that are targeted for the release must be merged in to develop at this point in time. All features targeted at future releases may not—they must wait until after the release branch is branched off.

The initial commit to release results in a release. Commits to release trigger automatic builds

Hotfix Branches

After final release the testing branch becomes the hotfix branch.

Hotfix branches support a specific release. They enable minor bug fixes to a release which can also be merged back to master. By doing this work on a hotfix branch, it is clear that this is a minor bugfix which is designed to fix a specific issue in a release.

Subsequent commits to testing result in point releases.

Git Workflow

Creating a feature branch

When starting work on a new feature, branch off from the master branch.

$ git checkout -b myfeature master

Switched to a new branch "myfeature"

Incorporating a finished feature on master

Finished features may be merged into the master branch to prepare them for inclusion in the upcoming release:

$ git checkout master

Switched to branch 'master'

$ git merge myfeature

Updating ea1b82a..05e9557 (Summary of changes)

$ git branch -d myfeature

Deleted branch myfeature (was 05e9557).

$ git push origin master

Creating a testing branch

Only the release manager should create a testing branch from the master branch when the state of master is ready for community testing. He creates the testing branch and gives it a name reflecting the new version number:

$ git checkout -b testing-0.3 master

Switched to a new branch "testing-0.3"

$ git tag -a 0.3

After creating a new branch and switching to it, he tags it with the version number.

Creating a release branch

Only the release manager should create a release branch from the testing branch when the state of testing is ready for the “next release.” He creates the release branch and gives it a name reflecting the new version number:

$ git checkout -b release-0.3 testing-0.3

Switched to a new branch "release-0.3"

$ git tag -a 0.3

After creating a new branch and switching to it, he tags it with the version number.

Creating a hotfix branch

After a release the testing branch becomes the hotfix branch

Incorporating a hotfix to a release

After testing, finished hotfixes may be merged into the release-* branch to prepare them for inclusion in the next point release:

$ git checkout release-0.3

Switched to branch 'release-0.3'

$ git merge testing-0.3

Updating ea1b82a..05e9557 (Summary of changes)

$ git tag -a 0.3.1

$ git push origin release-0.3

Incorporating a hotfix to master

If necessary, finished hotfixes may be merged into the master branch for inclusion in future releases:

$ git checkout master

Switched to branch 'master'

$ git merge testing

Updating ea1b82a..05e9557 (Summary of changes)

$ git push origin master