PlanYourPlace Software Development

From stgo
Jump to: navigation, search

return to PlanYourPlace

For the development of the PlanYourPace website and other software development we will use a software versioning and revisioning system, in our case Subversion (SVN). This is useful to store files and to track changes to these files, including restoration.

The development of webpages and scripting functions will likely be done with Aptana (which is based on the Eclipse platform).

Installing the Social Network Elgg on Ubuntu Linux

Note, I will detail this in future a bit more. For now I am linking pages only.

To run Elgg on your computer you should have a LAMPs system, i.e. Linux with the Apache web server, the MySQL database, and the PhP programming language.

Installing LAMPS : Apache, MySQL, PhP

how to do that for Ubuntu is described here: LAMPS for Ubuntu 11.04. Please note that you need to install tasksel first - which can be done with the "Ubuntu Software Center" function from the side menu.

Installing Elgg

new:

outdated:

Installing Aptana/Titanium

Aptana on Linux

The official install instructions for Linux are here: http://wiki.appcelerator.org/display/tis/Installing+Studio+on+Linux

What I did:
I created a new "progs" folder in my home folder. And then unziped Aptana into it. Renamed the Apatana Studio 3 folder to "Aptana3" and created a link file (right mouse menu) of the file "Aptana Studio 3". This link file I then moved to the desktop. Another option is - after having Aptana started - to click on the Aptana icon in the Ubuntu sidebar and chose "Keep in Launcher". So far I am running it on OpenJDK - not with Oracle/Sun Java.

Titanium

Titanium is a mobile application development environment developed by Appcelerator, who incidentally brought Aptana early in 2011.

The official install instructions are here: http://training.appcelerator.com/zero-to-app?mkt_tok=3RkMMJWWfF9wsRonv67BZKXonjHpfsX74uQoXqW0lMI%2F0ER3fOvrPUfGjI4HScB0dvycMRAVFZl5nQ1ICuOQcIVS%2B%2BFSGQ%3D%3D#102

Installing an SVN client

you may use the Tortoise SVN client or cliens that are integrated with Aptana/Eclipse (e.g. Subversive and Subclipse)

Installing SVN in Aptana

Aptana does not come with a build-in SVN client. There are two Subversion SVN clients for Eclipse - as I had problems with Subclipse I recommend using Subversive. Its installation and behavior should be exactly the same for Eclipse and Aptana.

The steps for the subversive installation should be as follows:

  • go in Aptana to the menu Help>Install New Software...
  • click on "Available Software Sites"
  • tick the box in front of "Eclipse Helios Update Site" (as Aptana 3 should be based on Eclipse version Helios)
  • choose that site in the "work with" field and wait until you get a list of "packages" presented
  • go in the package tree to Collaboration > Subversive SVN Team Provider
  • install this package (it also installs the dependencies that are automatically added) after agreeing to the license
  • after the Aptana restart the Subversive will install some more packages/libraries
  • you will be asked to chose among the SVN clients : chose the new "SVN Kit" version, which is in native Java (and not JavaHL - which is a bridge to a C client)

After this is done, you can go to Window > Open Perspective > Other.. and chose "SVN Repository Exploring" from the list. After the perspective changed to the SVN view click on the "New Repository Location" button (with a green plus) and add in the URL field: svn://subversion.engg.ucalgary.ca/hunter - then click "Finish". Its not necessary to provide your login right now - important is that this repository URL gets stored. Note also, that you need to request a SVN login previously (your UofC login will not work here).

Using the SVN

Versioning System Language: You can "commit" to the SVN, and "check out" files from the SVN. "Synchronization" is the process of comparing files in the repository with files in your local computer. "Updating" will overwrite local files with newer versions. Sometimes you need to add a new file to the version control ("add to version control") before you can commit - otherwise the file will stay a local file only.

SVN Location

the group repository is under this url: 

svn://subversion.engg.ucalgary.ca/hunter
  • there is one subfolder "playourplace" that contains the webpage
  • there is another subfolder "PYPSoftwareDevelopment" for our development material

SVN Structure

within the development folder we should have the following subfolder structure:

first you will find folders for the software we develop for - for intance a folder for Elgg. As we do develop plugins for Elgg that are independent of each other, each plugin will have his own folder. So the structure is a follows, whereby the subfolders trunk, branches and tags are SVN standard folders:

  • PYPSoftwareDevelopment
    • Elgg
      • ElggPluginName
        • trunk
        • branches
        • tags

Each plugin folder should contain the following subfolders and files:

  • trunk - contains the development source code (everything need to run the tools)
    • /src - contains the source code
    • /lib - contains all the libraries that are used
    • /etc - here we store additional things we need, such as build scripts and licenses
    • /doc - a folder for software documentation
    • changelog.txt - a file that contains a description of commits that are "important" changes to the source code. It can be used like the SVN commit comments, but can be more descriptive/detailed
    • todo.text - a file that contains ideas, tasks for future development. However, this may be replaced by an issue tracking system.
    • info.text - a file that can be used for some general info
  • branches - contains development source code, but they may not work completely (i.e. branches can be used to save your non-finished development)
  • tags - is for releases (stable); the folder will essentially contain a complete copy of the trunk folder for a certain point in time.

Helpful SVN Usage Guidelines

  • synchronize every morning/day before you start programming, and update all changed files
  • before you commit, do a synchronize to see if new conflicts emerged during the day (if conflicts appear, then you need to merge the documents manually - i.e. don't use update, because this will overwrite your changes - and check afterwards if everything still works)
  • only commit those files that you changed (you can use synchronize to actually see that)
  • always comment on your commit - write what ever appears to be useful to let you and others know why you did changes. This is important in case some things got broken and need to be restored later. For commenting, abide by the rule that something is better than nothing. Usually the amount of text here is 1-2 lines.
  • with (almost) every commit also put a comment into the changelog.txt file, saying what you did. Add a comment there, if your commit will influence the work of others (because you changed the structure), will change your future work, or you added a new feature. Also bugfixes should be commented here. Write as much detail as you think is necessary. However, things like the correction of spelling, adding code documentation or changing the names of variables do not need to be added there.
  • commit your new files and changes after you have a completed "one task" - i.e. don't wait until the end of the day and commit lots of different things together, smaller but more frequent commits are better so that you can see at a latter date what was done. Also commit before having breaks, such as lunch or coffee, etc., so things are saved in case you computer decides in the meantime to stop working.
  • as mentioned above, the sources in the trunk must always be working (e.g. can be compiled without errors). If you have stuff that can not be commited in the evening because it is not running, you may consider commiting it to a "branch" or "sandbox" (though.. you should know beforehand if you work on something more than a day until its commit-able - so you can branch first). But, it's important to commit the things you did, so they are safe in case something happens... worst case would be you just mark all things in a file as comments and commit then, so build processes don't get broken.
  • and then, not really an SVN thing, but: document the (javascript) functions you wrote using ScriptDoc, i.e. say what the function does (even if it seems trivial), describe necessary input parameters, preconditions if necessary, and outputs. Here also follow the rule.. better something than nothing, and better too much then too little. (Btw. in case you haven't heard it: a professional programmer spends approximately half of their time programming and the other half of their time documenting - if you split 60:40 its ok too.. but 80:20? nope.. then you are probably not documenting enough)
  • any questions? ask me, stefan.

Issue Tracking & Bug Tracking

We use the issue tracking software Mantis (an alternative is Trac). Issue tracking tools are used to define new functionality to be implemented and to report bugs. They can then be used to follow the implementation process (i.e. is the function accomplished) or the bug fixing progress. And, well... they allow the assignment of tasks to people (*yeah*).

Documentation Tools

Code Documentation: As we will use Aptana for development, it is best to use the Javascript documentation system ScriptDoc comming with Aptana. However, other software such as NaturalDocs (used by OpenLayers) or the JSDoc Toolkit are options for documentation as well.

useful links

Platform Architecture Documentation: needs to be decided how we do that, current favourites include using LucidChart for the charts/diagrams that describe the architecture and maybe Sphinx or/and ELML for writing the doc.

General Help on Programming and Tools

There is a great webpage called Stack Overflow where people can ask questions around software development. But, you should check there first if your question hasn't been asked already.

Software

MooTools (My Object-Oriented Tools)- an object oriented JavaScript environment. MooTools focuses on modularity and code reuse, and has many built-in methods for handling AJAX requests, CSS and DOM elements.

prototype is a framework to assist JavaScript development. It provides many shortcuts for dealing with AJAX requests and introduces class-based design to JavaScript. Prototype can be used to extend W3Cs DOM, which some consider to be controversial.

Books

Obcena, M. J. (2010). Pro JavaScript with MooTools: Learning Advanced JavaScript Programming. New York: Apress. Available as an ebook through the University http://proquest.safaribooksonline.com.ezproxy.lib.ucalgary.ca/book/programming/javascript/9781430230540

Retrieved from "http://wiki.geosteiniger.cl/mediawiki-1.22.7/index.php?title=PlanYourPlace_Software_Development&oldid=1065"