Submitting patches

Should you have found and confirmed a bug somewhere in the framework and you have been able to create a patch that solves the problem, then the easiest way to get your patch merged into the code base is to submit it in the JIRA bug tracker. The JIRA bug tracker can be found at this URL: http://jira.springframework.org/browse/SESPRINGACTIONSCRIPTAS

Your patch will subsequently be evaluated by a team member and based on their findings it will end up being included or not.

Submitting code or becoming a team member

If you want submit a piece of code that you deem of interest to the framework you can always send it to one of the team members.

Another way is to place a feature request in the JIRA bug tracker and attach your code to it.

When you feel you want to become even more actively involved in the project, please drop the lead developer a mail and express your interest in becoming a team member and what your specific area of contribution will be like.

When you commit code to the Spring Actionscript SVN repository there's a few coding guidelines to be adhered to, here's a list of the most important ones:

• Use Sun style bracing, like this:
  

            	public function methodName():void {
            		//implementation...
            	}
            

• Use the comment header containing the copyright information found in every .as file in the code base in all your submitted files.
• Suffix all event handling methods with '_handler'.
• Add sufficient unit tests for your code to the test applications.

Documenting your code

It is obligatory for all source code that is committed to contain decent ASDoc style comments. Use these comments to clearly explain what the code is supposed to be doing.

So documenting a method called getProducts() by stating 'This method gets all products' is NOT deemed a clear commentary.

The Spring Actionscript documentation build system is quite sophisticated and offers a few custom annotations:

• @docref docbookpage.html#section_id
• @sampleref sample-project-name
• @externalref http://www.someotherdomain.com

The first one can generate a direct link to the docbook documentation, you only need to add the name of the HTML page with an optional anchor link to a section id. The build system will expand the path to the appropriate documentation URL.

The second can link to an SVN directory that holds a sample project demonstrating the use of a class. Only add the direcotry name of the project that is directly under the 'samples' directory of the specified Spring Actionscript module. (e.g. trunk//spring-actionscript-core/samples/).

The third annotation enables you to link to an external site, so for instance, if you know of a Wikipedia article that can help a developer understand the concepts of your code, add the URL like that.

All of these annotations are currently only supported at class-level, adding them to ADSDoc comments for properties, methods, etc will not work. Also, due to a limitation of the ASDoc system, you can only add one instance of these annotations per class. So, two @docref annotations won't work, but one @docref and one @externalref will work nicely.

For more information about how the ASDoc comments work, visit: ASDoc at Adobe Livedocs

Adding articles to the docbook documentation

Besides the regular API documentation Spring Actionscript also offers a more in-depth documentation that explains how to use the framework in everyday developer situations.

It is not obligatory to add an article about your code, yet, it is greatly appreciated if you do. Adding to the docbook documentation will make the framework more user friendly and easier to get into for developers who are new to the code base.

As mentioned, this documentation is compiled using the docbook standard, for more information concerning this standard visit: docbook.org

When adding a section to an existing docbook page make sure to give the section an explicit xml:id attribute. When your section title is something like 'How to use this code', then give the section an xml:id value like this: 'how_to_use_this_code'. Otherwise the docbook build system will generate a unique id every time it runs, which would disable our ability to directly link to a part of the docs from, say, the forums or from the API reference docs. (As described in the section 'Documenting your code').

Giving the section a more human-readable id will also greatly enhance the way these pages will be indexed by Google, for instance.

For editing docbook pages the Spring Actionscript team recommends XMLmind XML Editor, of which you can download a free personal edition from this website: xmlmind.com

Finally, use the existing docbook documentation for reference on how to go about things.

Docbook documentation customizations

Spring Actionscript offers a few customizations to the docbook build system, one such customization makes it possible to link directly to the API reference.

For instance, in the section you are writing you are talking about your new class called XMLContextAdapter, to create a direct link to the API documentation of this class, encode the text like this: <literal xlink:href="asdoc://my.full.package.path.XMLContextAdapter"/>XMLContextAdapter</literal>

Or, if you want to link to a property or method: <literal xlink:href="asdoc://my.full.package.path.XMLContextAdapter#myMethod()"/>XMLContextAdapter.myMethod()</literal>

The docbook build customizations will then take care of generating the appropriate link.

Linking directly to a package in the API reference is done like this: <literal xlink:href="asdocpackage://my.full.package.path"/>MyPackage</literal>

To link directly to the configuration reference, encode your text like this: <literal xlink:href="dtd://anchor_objectType"/><object/></literal>. (Even though you might not need that one too often.)

Adding a link to an external URL can be done like this: <literal xlink:href="http://www.springactionscript.org"/>Spring Actionscript</literal>

And lastly, to link to a local file or page: <literal xlink:href="local://binary/myinstaller.air"/>AIR Installer</literal>