Docstoc

Downloading Code

Document Sample
Downloading Code Powered By Docstoc
					Welcome to Christmas Future Donor Trust.

*Need a clear description of what Donor Trust is and how it relates to Christmas Future

The Donor Trust Projects represent a decentralized community of committed volunteers working
cooperatively to achieve dramatic results that none of us could achieve alone. But not all Donor
Trust volunteers are developers! Many skills and much talent are required to manage and grow
an open source organization.

Donor trust currently split into 3 projects; Donor Trust, Christmas Future Administration and
Partner Administration. Other projects may come online as needed such as a module or a utility.
As particular areas are identified, scoped and staffed they will appear as Donor Trust Projects.

How to Get Involved!

The strength of volunteer projects comes directly from the strength of the people involved with
them. Christmas Future is fortunate to have and attract a strong community of users and
developers. We invite you to participate in our projects as much or as little as you are able. The
roles and responsibilities that you can assume are based strictly on merit... evaluated by your
peers.

There are a variety of ways for you to participate. But regardless of how you choose to
participate, we suggest you subscribe to any and all of the forums that interest you. Our forums
actually serve a similar function to mailing lists, allowing you to subscribe to a particular thread or
all threads in a particular forum... much like a mailing list.

Use the Projects and Give Us Feedback

Using the projects, testing, reporting issues, making feature requests, et cetera, is an essential
role. Your feedback helps the projects to improve and grow. You can:

    o   Download Project Files (modules, documentation, etc.)
    o   Subscribe to User Oriented Forums (keep up with what's going on)
    o   Participate in User Oriented Forums (ask questions, offer help, report issues, request
        enhancements)

Contribute Code Patches or Documentation

To quote Cameron Wiley, of Apache's Jakarta project...

"Opensource doesn't improve by advocacy, mindshare, or by having 10 million users; it improves
by the participation and contribution from the user community."

In this role, you can participate in the actual development of the code at the "patch" level. If this
is the type of role you'd like to play, you can do that by hanging out in the "Developer" oriented
forum for your favorite project, testing code, addressing issues locally and offering suggestions
for fixing them. If your contributions take root, you can work yourself into a project team role if
that's what you have passion for. In addition to the above, you can:

    o   Participate in Development Forums (identify issues, offer solutions, discuss alternatives)
    o   Subscribe to the Project Issue Log (receive notice when issues are updated)
    o   Contribute Documentation or Other Deliverables (if you've done something interesting, it
        might find a home with other project files)
By submitting a patch, documentation or any other contribution you signify your understanding
and acceptance that it remains under the license of Christmas Future and attest to your rights to
submit the contribution. Or... in plain English... you're saying that you have the legal right to give it
to us and that it isn't somebody else's property.

Apply to Join a Project Team

Each Project Team has a Lead and team members. The Team Lead is responsible for
assembling and managing their team and orchestrating the advancement of their Project.

Being a member of a Project Team is a big step. Team Members have access to the
Project's source code repository, private discussion and download areas. In order to join a
Project Team, you'll need to contact that teams Lead and determine what their individual needs
and criteria are. Some Projects are large and complex, some small and straightforward... but all
require a written Contributor License Agreement. This agreement simply puts in writing the same
terms described above, but is required "in writing" to gain access to the Project source code
repository and other resources.

What are we looking for in a Project Team member?

       Responsibility ~ Don’t apply if you can't afford to commit a few hours a week to
        participating. Team Members are expected to actively contribute to their forums and to
        the project development and Issue management. Specific responsibilities are up to the
        Team Lead, so you can work out your level of contribution with them.
       Attention to Detail ~ Quality is a priority. We need developers who actually test, testers
        who are thorough and tech writers who can write for Users and Developers. The Issue
        Logs for the Projects are open to public view, but are maintained solely by the Project
        Team Members. And documentation, help and user experience are valuable aspects of
        all projects.
       Teamwork ~ We work as a team. This means that sometimes there is frustration
        because one person or another KNOWS they have the right answer if everyone would
        just listen! However, the Christmas Future meritocracy works partly because of our
        commitment to work collaboratively through issues to find the right answers. This
        sometimes slows things down a bit, but the end results prove better and more robust. If
        you can't convince your teammates of the appropriateness of a solution, there's more
        work to be done... either on the solution or the problem definition.

If it is your goal to become a Christmas Future Core Team Member. You must first begin as a
Project Team Member. You'll gain a little insight on what it’s like to work "from the inside" and
we'll get a chance to know you a little better...


Christmas Future Donor Trust Server Information:

Code Base: Ruby on Rails (ver. 1.2) http://www.rubyonrails.org
Server O/S: Unix
Web Server: Apache with Mongrel http://www.apache.org & http://mogrel.rubyforge.org
Development IDE: RadRails (ver. 0.7.2) http://www.radrails.org
Database: MySQL 5.0 Community Server http://www.mysql.org/downloads/mysql/5.0.html

Server: xmasvm1 (or 10.99.1.146)
Logins: webdev (pw xmasf1)
       root (pw xmasf1)
Site is hosted off of /htdocs/xmasfuturedev
You can hit the site at: http://xmasvm1.ideaca.com/ there is currently just a test index file there.

Mysql is accessible via ‘root’ with the same password as the root user (xmasf1).


RubyForge Information:
*Insert description of the RubyForge Portal
Project Full Name: DonorTrust
Project Unix Name: donortrust
Virtual host:     donortrust.rubyforge.org


Donor Trust Portal:
Site: http://portal.christmasfuture.org
Section: dtrust (donor trust) tab

To obtain access: email @techs@ideacacom to request access to the portal.


Development Environment Set-up:
*Need the instructions on setting up a developers IDE – I believe Michael and/or Christian has all
the notes on this
Rails Overview/ Architecture
Ruby on Rails is a technology that was created to make data centric web-based
applications quick and easy to build. All Ruby on Rails applications are built on the same
architecture, Model-View-Controller. The idea here is that because assumptions are
made in the framework about how the developer will do things then the developer doesn‟t
have to spend effort telling the framework how they are doing things. Therefore, more
effort is spent on the tasks at hand and less time is spend with configurations.

Rails was created with three main ideas in mind:

   1. Convention over Configuration – by following the standards enforces by rails less
      configuration is required.
   2. Instant Feedback – Rails makes it easy to apply simple changes that are easy and
      changes are visible instantly
   3. Full Stack Framework – Instead of pulling in plug-ins from multiple vendors
      Rails offers a framework that provides components commonly used within a web
      application.

The main components/services that make up the Rails Framework are defined below just
for interest sake. It‟s not required that you understand these components in detail but you
will probably see the terms used.
        1. ActionPack – handles dispatched requests, controllers and views. It also
             defines and handles URL routes. The ActionPack will interact directly with
             ActiveRecord, ActionMailer and ActiveWebservice.
        2. ActiveRecode – is the object relational mapping layer. It handles all models
             and is database agonistic
        3. ActionMailer – handling delivering and receiving emails
        4. ActionWebservice – supports both SOAP and XML-RPC webservices.


As already mentioned Rails follows that Model-View-Controller pattern.

       Models – Rails interacts with models through the ActiveRecord component. An
       ActiveRecord model encapsulates a row in the database and domain logic
       associated to the data. It allows for validations, associations and other behavior to
       be contained within the model class. Models are associated with a database table
       through proper naming conventions. A model is named in a singular fashion and
       the database table the plural version i.e. organization – organizations. The only
       thing that requires configuration is the database connection information. A model
       is a object relational mapper that requires little configuration because it‟s assumed
       that certain conventions are followed.

       Views – are the rendered response to a client request. Rails offers three types of
       views; RHTML, RJS and RXML. I won‟t mention these any further because for
       our project we will be using AJAX for the views. AJAX will be discussed later in
       this document.

       Controllers – are the center of a Rails application. Controllers take a request and
       decide what to with it. They interact with Models, choosing with view to render
       and any redirects that take place. They group multiple actions into one class i.e.
       add, edit, delete.

Below is a diagram that I have graciously borrowed as I think it does a great job
depicting the lifecycle of a request through the Rails framework. Hopefully it is useful to
you also.




Directory Structure
When a new Rails application is created it automatically creates a directory structure for
you. Of course we will follow the structure provided as its all part of the Rails magic.
The folders are listed and described below:

        app            Holds all application specific code (models, views and
                       controllers). Also stores apis and helpers. The app folder is the
                       heart of the application and contains some important subfolders
                       that are self explanatory; controllers, helpers, models, views.

        component Components are self-contained packages of controllers and views.
                  Used when there is a need to reuse views and the behavior
                  associated to it.
        config    Stores configuration files for the rails environment. Database
                  connections and other configurations are stored here.
        db        Houses the database schema and migration files.
        doc       Holds the application documentation that is created by RDoc
        lib       Stores application specific libraries
        log       Location that stores the server logs.
        public    This folder is public to the web server. Images, stylesheets, java
                  script, static html pages etc are stored here.
        script    Stores helper scripts for the development server, automation,
                  generation and plugin management.
        test      As the name states this is where all unit and function tests are
                  contained.
        tmp       A temporary directory for the development server
        vendor    Contains any external plugins and external libraries required by the
                  application.

Additional Development Tools

As we have discussed, we are going to use additional tools to support the development
effort where it makes sense. There is no point reinventing the wheel if we don‟t have to.
Described in this section are some of the tools that have already been decided on but it is
expected that we will extend this through the life of the project

       Ajax
       So what is Ajax anyway? Ajax stands for Asynchronous Javascript + xml, it‟s not
       really a tool but more of a concept. Ajax is a way of thinking about the
       architecture of a web application using certain technologies.

       In an Ajax application user actions that would normally generate an HTTP request
       instead takes the form of a JavaScript call to an Ajax engine. Any response to a
       user action that doesn‟t require a trip to the server, such as data validation, the
       engine handles on its own. When the engine requires something from the server,
       such as saving data, the engine makes the request to the server asynchronously
       using xml, without stalling the user‟s interaction with the application.

       Recently toolkits and frameworks have been created to encapsulate a lot of the
       common functions and UI components used to develop an Ajax web-application.
       For Ruby on Rails specifically the two main frameworks are Prototype and
       Script.aculo.us.
       Prototype is a toolkit that enables developers to handle Ajax calls easily. It
       encapsulates all the redundant code required for things such as handling cross-
       browser functionality. Prototype also provides DOM extensions helping to
       simplify development using DOM.

       Script.aculo.us is an add-on to the Prototype framework. Where the prototype
       framework focuses on extending the baseline capabilities of JavaScript and the
       DOM. Script.aculo.us allows developers to make HTML look and act like any
       other “rich client” platform. It provides things like drag-n-drop and sortability.

       Prototype and Script.aculo.us both come packaged with Rails therefore making it
       easy for us to use these libraries through the development of DonorTrust.

       Do we want to list specific plug-ins
       Only the ones we want to use in the site


Coding Standards
Coding standards or conventions are very important for any project but are especially
important with open source projects because the team usually consists of people with
diverse backgrounds. Considering Ruby is new to most of the team we will try to make
these standards comprehensive yet they are not set in stone. The following standards are
open for discussion and will change where it makes sense.


       Code Comments
       It is expected that each developer will comment the code they write. The intent is
       not to comment every line of code as it can become littered with comments and
       hard to read. The expectation is that complex sections will be commented to
       explain the intent. Also any code that requires refactoring or changes should be
       annotated with a “FIXME” tag. (This seems to be the Ruby standard, if people
       prefer we can us “TODO”)

       Comment Blocks should use Begin-End blocks
            =begin
              Comment goes here
            =end

       Single line comments should use „#” tags

              # Comment goes here

       Comment Blocks should be placed at the beginning of all files for description and
       should look as follows”
       =begin
        * Name: File/Class name
        *Description: Description of Class
        *Author: Created by Developer Name
        *Created Date: No explanation needed
        *History: Developer Name, Change Date, brief description of change
       =end



Conventions
Ruby on Rails focuses on convention over configuration therefore some files must
be named appropriately. Models must be singular and the database tables must be
the plural version of the model. Controllers should be suffixed with “controller”
Additional naming conventions are listed below:

1. Classes and Modules
        Class and Module names should follow the Camel Case format meaning
        that all words are joined without spaces and each word is capitalized.
        Class names should be nouns. Modules names should be adjectives.

2. Methods
       Method names should consist of all lower case and words should be
       separated by underscores. Method names should be descriptive.

3. Variables
        Single character variables will not be tolerated always use descriptive
        names, most likely verbs. Variable names should be lower case and words
        should be separated by underscores. All variables should be initialized and
        each initialization should appear on its own line. Global variables should
        be avoided.

4. Constants
       Constants should consist of all upper case and words should be separated
       by underscores. Constants names should also be descriptive, generally
       consisting of nouns.



(stuff to pull in from Christian‟s presentation ??)

@ - prefix instance variables
@@ - classes ??
Ruby is flexible and offers many ways to perform the same task….should we get specific
about this? -Lets be explicit.
I like the standards you listed below – it‟s common enough and isn‟t too rigid.

-Don‟t use semi-colons
-lines should be <80 characters and should be separated by a comma or operator
- 2 blank lines between each class or modules definition, 1 blank line after methods.
- Indentation should be 2 spaces between each logical level.
- use && and || instead of „or and „and‟
- Only one statement/line.



       Exception Handling

       It is important to provide exception handling for application integrity and a user
       friendly experience. Exception handling should be contained within a
       „begin…..rescue…..ensure…..end‟ block.

               begin
                #Code goes here
               rescue
                #exceptions handled here
               ensure
                #clean up happens here
               end


       Error Messages
              - Do we want to get specific about this?


       Logging

Speak with Christian

       Developer Testing

       For anyone who is unfamiliar to Test-Driven development please refer to the links
       at the bottom for detailed information. Here we will just highlight standards and
       naming conventions associated with testing our application.

       It is intended that all developers will test their code. Some individuals do not
       subscribe to test-driven development so really we are simply asking that you write
       your tests while writing your code. Code should not be checked in unless it has
       comprehensive tests associated to it.
       Test cases should include both positive and destructive scenarios, meaning that
       you if you expect a user name to be less than 20 characters you would test that a
       user is created when the user name is less than 20 characters and you would test
       that a user is not created when the user name is greater than 20 characters.

       Testing is especially important when you potentially have multiple people
       working on the same code. It will ensure that you understand what the code is
       supposed to do, how it is supposed to perform. Also it will ensure that your
       changes will not break functionality in other areas of the application.

       The testing directories live in your application under the directory called “test”
       and contains the following sub-directories:
               fixtures
                  Fixtures allow you to populate your testing database with data before
                  your tests run. Fixture stubs are created when you create a new model.
                  The fixtures are created in YAML which is a user friendly way to
                  create sample data. CVS files are also be used to create sample data
                  but our standard will be YAML.
               unit – used for testing models
                  Unit tests are used for models. A Test Case stub is created when you
                  create a new model. Test Case files will follow the name convention
                  „modelname‟_test.rb. You should have at least one test method for
                  every method in the model but considering we will be testing both the
                  positive and destructive scenarios you will generally have multiple
                  tests for each method. All test methods should start with “test_should”
                  then something descriptive for what the test will assert (i.e.
                  test_should_create_user).
               functional
                  Functional tests will test the controllers. A new function test is created
                  with each controller and are named „controllername‟_test. Functional
                  tests operate at a higher level and test things such as authentication,
                  did a page redirect work as expected, etc.
               integration – used for integration tests
               mocks – stores mock objects

       I recommend reading about testing as it relates to Rails as it provides lots of
       functionality to support your testing effort, again please refer to links provided.


Code Management
The intent is to manage most of the development activities through RubyForge, making it
a one stop shop for developers. Of course where it makes sense we will deviant. ??

       Bug Tracking
Bug tracking is a common attribute of any software development project and
considering that this is an open source project it becomes more important to keep
everyone informed about the state of the project and the bugs that need to be fixed
by themselves and others. It is also important to managing releases as far as the
state of the release and the bugs that were fixed for each release.

RubyForge offers built in bug tracking that will satisfy the needs of our project. It
is also customizable to allow us to modify it as needed.

Outlined below are the fields and attributes for bug tracking within the
DonorTrust project.

      Category
      UI Related           Error exists in the User Interface
      Validation           Error with a validation (i.e. Phone number
                           validation incorrect
      Runtime/Script       Application error, generally a hard error not
                           captured by the application
      Usability/Navigation Issue with page flow or navigation link incorrect
      Functionality        A user requirement or functionality was coded
                           incorrectly.
      Enhancement          Functionality was coded to requirement but no
                           longer makes sense or needs additional functions

      Groups (supposed to be a specific module name maybe like donor?)

      State
      Open                    Bug is open and active.
      Closed                  Bug is completed, regardless of status
      Deleted                 Bug has been deleted.


      Status
      New                     Always default when adding a new bug.
      Assigned                Assigned to a developer
      Complete                Developer has completed the bug
      Tested                  The bug has been successfully tested
      ReOpened                If testing failed bug is reopened

      Severity
      Critical                Usually a system crash, data lost or incorrectly
                              saved, security issue
      Function Broken         A requirement doesn‟t work because of this bug.
      Inconvenience           The bug interferes with the functionality but a
                              workaround exists.
              Cosmetic                The bug does not interfere with the functionality

              Priority
              Urgent (5)               This bug is severe and restricts usage of application.
                                       These bugs should be fixed as soon as possible
              Fix before Release       These bugs should be fixed before a new version is
              (3)                      released to production
              Normal (1)               These bugs impair functionality but may not require
                                       fixing right away.
              * Ignore the rest of the numbers. There doesn‟t seem to be much benefit
              for 5 levels of Priority

              Assignee
                                      List of Contributors will be added to the Selection

              Summary
                                      At a glance description of the bug
              Detailed Description
                                      A detailed description of the bug and how it was
                                      produced so others can reproduce it.

              Attachment
                                      Attach a file just as a screen shot of the error
                                      message, or data used to produce error. Please
                                      attach a screen shot where it makes sense.

              File Description
                                      A quick description of what the attachment
                                      contains.



Documentation

Submitting Code

Two Structures will be in place.

Release Candidate
One set of code will be a Release Candidate. Core testing will be done from this code
base and has potential to be released to production. Code within this environment will be
restructured. All developers can download the code but can not make updates.

Development Branch
Developers will work from this branch. Developers will use this branch throughout the
development process. They will have the ability to get latest as well as check code into
this branch?? (EXPAND: Include information about how submissions will work)

Do we need another branch……one where the developers work from and another where
they submit their code? This is harder to manage as an individual will need to always be
reviewing submissions and moving them to the development branch.
Build Management??
*We should also have a strict release management process



Downloading Code

Do we need to explain how to download the code or is that something for Michael‟s
Document?
*Could be in Michael‟s doc but I think we should put it in this document

Methodology

Our Project will be developed using an Agile Process. For anyone who has not worked in
an agile environment, the idea is that you gather only enough information that you need
to understand scope and detail out requirements as they are being developed. You start
with user stories, which is a statement of commitment to discuss the requirement later.
Basically a user story fills in the following statement.
        “As a <type of user> I require the ability to do <requirement> so that I can
        <value> .“.
The user stories are listed in something called a product backlog which is used to fuel the
development process. High priority tasked are pulled from the backlog in an iteration
which is usually 2 – 4 weeks of time where the developers complete the tasks that were
committed to. At the end of the iteration the completed functionality in demonstrated to
the users, as well the tasks for the next iteration are decided.

How we came to where we are

We started with brainstorming sessions to gather requirements and desires for the
DonorTrust application. These requirements were captured in a document and
transferred to User Stories. All user stories were added to the product backlog, which is
stored on RubyForge. Could we not just use the task list provided?
* Yes, or what ever list is provided on Ruby Forge

The development process

Our iterations will consist of 4 weeks of development time. At the end of each iteration
we meet to show off our work and plan the next iteration. Developers will also meet on
Fridays from 4-7, currently at the Ideaca Office, to discuss an issue, and continue to code
as a team. These meetings aren‟t a requirement as we intend to have developers that
aren‟t necessarily located in Calgary but anyone who would like to attend is welcome.

Everyone is also encouraged to use the discussion board on RubyForge for all
communications related to development; this ensures that information is always shared
with the entire team. This may also help any new developers joining the team get up to
speed a little quicker.

The key here is that our desire is to be agile and adapt as the project moves forward. To
ensure smooth development cycles we will discuss the things that are and are not working
to adjust our process as necessary. Everyone is giving up their own time to contribute to
the success and values of ChristmasFuture therefore it‟s important to ensure that
everyone on the team is valued and enjoying themselves while consistently being aligned
with the values of ChristmasFuture. <Should we list the values?>

What am I missing….I feel like I am missing something??
*looks good, we‟ll expand more as firm up the process




Links
      Portal, RubyForge, Christian‟s Links
*Added above

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:17
posted:3/7/2010
language:English
pages:14