Assembly Competition Tutorial

I. Introduction

Assembling at TopCoder

TopCoder has created Assembly Competitions as an extension of the Component Design and Development Competitions. Through assemblies, competitors will create high quality applications using completed components and TopCoder's established competitive method.

Assembly competitions are hard to define. They can adopt different forms and have distinguished goals and results. Other than "regular" application assembly (that is actually assembling components to build part of an application) we can find other types of assembly projects like Prototype Conversions, Release Assemblies and even Proof of Concept assemblies.

All these kinds of assemblies will have something in common. They will all require the assembler to build a working piece of an application that will represent another step of refinement in our iterative model.

On the other hand, each kind of assembly could involve a great variety of applied technologies. Programming languages, frameworks, environments and other technical characteristics will be determined for each project. This tutorial will cover the assembly process without any ties to specific technologies.

You may also find very valuable the development tutorial. Assembly guidelines are often simple extensions from those from development, so you will notice great similarity between this tutorial and the development one.

Assembly process

You can think of the assembly process as a refined iteration that needs to transform low level artifacts into working code closer to the final application. You will be given a set of artifacts: specification documents, architecture documents, working components, design documents, prototypes, etc. and will be tasked use these artifacts to build a working part of an application. When you have completed your task, your submission will be reviewed by the Assembly Review Board. If you are the winning assembler, you are then tasked to fix all those issues recommended by the Review Board. Once complete, your submission undergoes a Final Review, and you're done!

Required software

As it was mentioned before, assembly projects may cover very different technologies so the software necessities may vary. Here is a short list of the language specific software that you are likely to find as required in a great percentage of assemblies.

C#

Tool	URL	Description
NAnt	Homepage	NAnt is a utility that executes custom, extensible build scripts. You will probably need this tool to compile and deploy your project.
NUnit	Homepage	NUnit is a framework that will allow you to quickly and concisely test your code.

Java

Tool	URL	Description
Ant	Homepage	Ant is a utility that executes custom, extensible build scripts. You will need this tool to compile and deploy your project.
JUnit	Homepage	JUnit is a framework that will allow you to quickly and concisely test your code.
Checkstyle	Homepage	Checkstyle is a format checker. You should check your source code format with Checkstyle before submission, if possible.

One tool common to all languages here at TopCoder is a UML design tool. TopCoder community has developed its own UML design tool called "TopCoder UML Tool". You can download the TopCoder UML Tool for free from the TopCoder website. Apart from these, you will also need word processing software (Rich Text Format - RTF compatible), a text editor or an IDE of your choice.

Any special software needs and technologies will be specifically stated in the Assembly Specification Document and in the project's details page.

Development environment

The development environment will also be specific to the assembly project. While some projects will detail all the steps to build your own local environment and encourage you to work that way, others will provide you with a fully working Virtual Machine for your convenience. There are also some project that will simply let you choose whether you want to setup your own environment to work comfortably in your local machine or skip all these preparations to be able to get your hands to work as soon as possible.

Registration

To participate in any assembly contest, you must first register with TopCoder Software. Registration not only allows you to submit assemblies, but also allows you to compete in several TopCoder tracks. To register, follow this link.

II. Picking a project

Picking a project is the first step to a winning assembly submission. You can quickly find open assembly contests at this page. From that page, you can see which projects are open, when registration ends and when submissions are due. These dates are very important. You must indicate your interest to develop a solution by the "Registration Ends" date. Your entire solution, with all required deliverables, is due by the "Submit by" date.

Project details

Clicking on the name of any project will bring you to the details for that project. Here you will find detailed information about the project, links to documentation for the project, payment information, and a more comprehensive timeline.

Deciding on a project

Project details page will give you a very brief summary about the project. After finding a project that interests you, your second step will be to take a good deep look at the Assembly Specification Document. This document is posted in the Project's forums. (You can find forums link in that same project details page under "Documentation")

To be able to access those forums you'll have to register for the project (you can do it from the project details page). While registering, the Terms of Use acceptance will grant you permissions and you'll be able to go to the forums and review this document. It's very important to read it carefully and identify:

Required technologies.
Provided artifacts.
Tasks to perform and expected deliverables.
Any other details regarding the competition.
Scope.

This last bullet is probably one of the most important. You should always be sure about the scope, so if you read the Assembly Specification Document and you are not confident the scope is completely described, you should always ask any related questions in the forums to clarify those doubts. Project Manager will always be happy to work out any ambiguities or inconsistencies, and the sooner these are clarified (while the competition is underway) the better.

Before choosing a project, it is very important to ensure you will have enough time to complete the project. Consider your other responsibilities and assignments for the scheduled development period. Also, keep in mind that the assembly may involve some technology you are not familiar with. Do you know how to use database connections in C#? Do you know how java.lang.ref's classes are used? Be sure to review all Specification sections before you judge your commitment.

Project un-registration

Remember that if you decide not to compete in the project you've registered to for any reason, you can always un-register while registration phase is open. You can unregister from a project by simply contacting the managers (from within Online Review project page) and ask them to be eliminated from that project. Un-registering will not harm you in any way and will prevent your reliability from being affected if you don't intend to submit.

The importance of reliability

High reliability means more money. Since TopCoder beneficiate by knowing (with some level of confidence) that there will be submissions for a given project (by looking at registrants reliabilities), they compensate competitors for this. If you always deliver when you commit for a project you will get bonuses (up to 20%) that will make some projects even more appealing. You can read more about reliability here.

The Digital Run (DR)

When picking a project you will also want to check if it counts for the Digital Run and how many points it will give you. There are some different strategies to approach the Digital Run, but the key points you must know are:

Assembly digital run points count for the Software Development Cup.
Component Development projects also count for this Cup.
You will earn more points when fewer competitors submit.
Digital run points are not always proportional to the project's prize. Sometimes PMs give an extra incentive with more generous DR points.

III. Getting started - environment

After registration, you'll have access to the project submission application known as Online Review, as well as a forum for your project.

Project submit and review

Project Submit and Review is the central hub for all contests you participate in. You will upload your submission via this application, and you receive your review scores here as well. To begin, go here, and log in. Once logged in, you will see a list of all your open projects, as well as your status.

Click on the name of the project to view the timeline for the project, or to see other more detailed information. At the bottom of this screen, you will have buttons appropriate to the current phase of development. Additionally, there is a button marked "Contact Product Manager". You can use this button at any time to send questions, comments, complaints, or any other information to the Product Manager.

Developer forum

A link to the development forum for your project is also available from the project detail page. Most communication regarding your project will take place on the forums. Your TopCoder username and password should allow you to view the Developer Forum for your project. If it does not, contact your Product Manager immediately.

Assembly specification and distribution

On the developer forum, there will be two sections: Development Phase Documents, and Development Phase Questions. You will find the Assembly Distribution for your project under Development Phase Documents. The Assembly Distribution should contain all the files and documents necessary to start development on your project.

The distribution content may vary according to the selected project. Some will just consist of an Assembly Specification Document defining all the tasks and deliverables. Other will refer to JIRA tickets for the requirements. There could also be component attachments, other documentation, prototypes, etc.

Setting up your environment

As mentioned before, some projects will let you create your own environment by specifying all required steps to build it locally and other will just provide a Virtual Machine instance. In both cases you will be given very complete documentation about how to build or use your environment.

IV. Getting started - development

At this point you have your environment setup, a set of artifacts to use and the Assembly Specification governing them all. You are ready to start developing!

Following are some advices you will find very useful, mostly if it's your first project.

The forums are the best complement for the specification

You should make extensive usage of the forums to clear up all your doubts, show potential problems, propose enhancements and improvements, etc. It's not only what you ask in the forums, it's also what your competitors ask! All clarifications given in the forums will be taken by the reviewers and verified in each submission so be sure to be up to date with the posts.

Keep deployment in mind

Since assemblies require integrating several components and technologies into applications that could be fairly complex, you will be asked to provide a deployment document with all the information regarding your submission. It's a good practice to keep this in mind while developing and make notes about what is going to be needed in this document so that it's not forgotten. (An example deployment document will be evaluated in the next section - Documentation)

Put yourself in the Project Manager shoes

This is not a functionality-narrowed component. You are building part of an application so it's important to keep in mind the big picture. This will help you identify possible problems and also discover useful enhancements.

Follow the development process

You can find more information about the development process such as common component contents, coding conventions, etc. in the Development Tutorial - Section IV.

Project structure

Each project will specify the required deliverables and their format, but there is a basic common approach to arrange your submission. The source for your project will reside under /src in your project directory. It will be accompanied by other directories for instance:

Path	Description
conf/	Any configuration files necessary to your submission.
docs/	All the documentation for your project. Deployment Document must be here.
src/	All your source code will be placed here (including test code).
test_files/	All files used in testing will be placed here.

Remember that each project could have its own standards and structure. If you have any doubts about what to submit, be sure to ask.

And you're off!

At this point in the tutorial, you should be ready to develop your project. Any more specific information on assembly technique or strategy is beyond the scope of this document. However, for the next few sections, we'll walk you through documentation and some common issues, common to all projects.

V. Working towards your submission - documentation

Documentation is critical to make any application maintainable. If you document your code as you write it, you probably won't even notice the burden of writing a project's worth of documentation. Your submission will be assessed on the quality of documentation. Furthermore, the better your documentation is, the easier it will be for the Review Board to understand and evaluate your code, and the better your overall score will be.

Documentation is important in all aspects of your work, from inline code documentation, documentation specific for reviewers, deployment process, etc.

Following are some advices you will find very useful, mostly if it's your first project.

Code documentation

Documentation standards are the same from those defined in the component development process. You can find more about code documentation in the development tutorial. Note that all delivered artifacts need to be properly documented. You should verify with the Project Manager any special documentation needs but always assume that documentation is needed.

File headers

You should include documentation headers in any file you submit (as possible). These headers help quickly identify the purpose of that file, keep changelogs, authors information, copyright, etc.

Deployment document

This document is targeted the deployment engineers that will deploy your application to the final environment. You should interpret "final environment" according to each project status. In some project this will mean a development environment such as a Virtual Machine. In others it will refer to the final production environment. If there are any doubts about the final environment and its characteristics, you should ask any related questions off hand in the forums.

You can find a template for building this document here. Please review it carefully. You will notice in each section information about possible content. Remember that this is a template, projects may have different deployment needs to be addressed.

Review guidelines document

Since the deployment document is meant for final environment it's not always suitable for specific information for reviewers. It's a good practice to include a brief document (it can be as simple as a text file) that will help reviewers deploy and configure the solution for review. In this document you will find specific information about how to deploy your submission to an intermediate QA environment (such as a Virtual Machine), specific configurations for this environment, sample scripts with test data, etc.

You should be able to differentiate deployment issues that concern review from those that concern the final deployment. Reviewers will evaluate this since it will be crucial for a smooth, organized deployment.

VI. Working towards your submission - problems

During the course of development, you may run into any number of problems. You may need a component from the catalog. There may be some flaw in the specification that blocks development. You may have questions about required functionality, or some technology employed by your project. Have no fear, you're not alone!

If you find any confusion or ambiguity in the specification, bring it up on the forums for your project (available from Project Submit & Review). It's possible that you've found some case or situation not covered by the specification. It may be that you're misreading the documentation, or overlooking something. In any case, problems specific to the project itself should be addressed on the forums.

On the other hand, if you have problems writing your code, or if you don't understand a required technology, or bugs in that regard, you should probably go to TopCoder's Round Tables, and not the assembly specific forums. The TopCoder Round Tables are available at this URL: http://www.topcoder.com/rtables/index.jsp. The Round Tables are frequented by many of the highly experienced TopCoder members, as well as TopCoder Software staff, who will always try to help as best they can.

If you ever have a problem that blocks you from working on your project, email the Project Manager immediately. This includes things such as missing or corrupt files, access or application problems, and any other important issue. You can email your Project Manager from the Project Submit & Review Details page for your project. If you can't access Project Submit & Review, email support@topcoder.com, and indicate which project you're registered to, and the nature of your problem.

VII. Submission!

First, you should review your code. Make sure that your submission meets the review guidelines (Section IX) as fully as possible. Finding small issues now will save you points later in the review process. Make sure that your directory structure is also appropriate and you have all documentation written down.

Once you're satisfied with your submission archive, you can upload it through Project Submit & Review!

Tip: once you have submitted your solution in Online Review, take an extra moment to download it to be completely sure you have uploaded the correct file and that it's ok. You would be surprised to find out that more than once you'll make some naïve mistakes that could cost you being disqualified from the project.

VIII. Review

The submission is out of your hands, and the Review Board will now judge it. This phase will consist of testing the deployment of the application, running all test cases and reviewing the application code. Each submitter will have a scorecard set up in Online Review. Reviewers will score each submission based on a scorecard. The scorecard will ensure all requirements are met and the proper use of all components as outlined in the contest deliverables as well as ensure that all code follows TopCoder guidelines.

Here is the latest list of assembly scorecards:

IX. Appeals

After review is complete, you will have a few days to view and appeal the score your solution was given. You'll see the comments from the Board on each point of the scorecard, and you can dispute any score. Please keep in mind that you must have a very good reason to appeal, or it will be denied. Take into consideration that matters of opinion may not be appealed.

X. Final Fixes

Congratulations! You're the winning assembler!

However, there is probably still work to be done. Your review scorecard will be available via Project Submit & Review, and there you will find any and all problems the Review Board found with your submission. It will contain required and recommended fixes to the submission as received.

Every single required fix must be addressed. Your submission WILL NOT be completed until they are. Every recommended fix should be attempted. Obviously, they follow the required fixes in priority, but if there is time, they should be completed.

Communication

More than any stage of the project, communication during final fixes is key.

If, for any reason, you have a question or comment on the review, post it as soon as possible. If there is any blocking issue, email the PM immediately, and post to the forum. The PM will look into the issue, and ensure that the primary reviewer is on top of things. If, for whatever reason, you feel a required fix is impossible, you need to address it on the forums. Do NOT just resubmit without the fix done, or a comment in a readme. This is never acceptable. Communicate with the reviewers to avoid these conflicts! The more detail you can give, and the sooner you give it, the more smoothly this stage will go. The Review Board is always open to communication from the developer; they may have overlooked something in the specification or in your submission. Don't be afraid to question the Review Board. Questions and comments show that you're paying attention and actively involved; without communication, the Review Board doesn't know that you're working on the fixes, and can't clarify their requirements.

XI. Final submission and review

The format of this final submission is just the same as the first one. You are encouraged to add a small text file indicating the fixes that were made to make reviewer's work easier and speed up the process. Try to be as complete as possible before resubmitting. This saves everyone time, including you.

If you've met all the requirements, and all the review tests still pass, the project is complete. Your work is complete!

If anything is not done, you've earned a return trip to Final Fixes.

XII. Support

The first place finisher will be awarded 75% of his/her prize at the completion of the Assembly competition (after Final Fixes). The remaining 25% of the prize will be awarded after the first place winner has successfully supported his/her work as described below.

The second place finisher will be awarded 100% of his/her prize at the completion of the Assembly competition.

After the Review phase, the winning submission will move on to the Support phase. The winner will support the application for 30 days following the Final Fixes phase, including performing all bug fixes. After the 30-day support period, any identified bugs will run through the standard TopCoder bug fixing processes which the winner may or may not choose to participate in. Any requests for enhancements will result in additional payments to the winner.

If a defect is found in a component, it will be fixed through TopCoder's standard component bug fixing process. An appropriate deadline will be set to fix the component and the winner will integrate the patched component once it has been fixed. If the component fix falls outside the scope of the 30-day support period, the winner will be paid additional money to integrate the component into the application once it has been fixed.

XIII. Sample Assemblies

The following assemblies will give you a better idea of the assembly process, its deliverables and sample interaction. It is highly recommended that you review these pages.

TopCoder Direct Flex Widget Submission Viewer Assembly 1 1.0

Flex Widget Framework Prototype Conversion Assembly 1.0

XIV. Common Issues

Here is a list of common issues that you may run into while developing your project. Some advices are also given.

Problem	What to do?
What do you do when you find scope problems but have already committed to the project?	Remember that you can always talk with PMs about anything unexpected. PMs will consider all your concerns and could leave some requirement for final fixes, for future work, give extensions, etc. The only thing you should not do is to keep silence.
What do you if there is a continuous requirements change?	This is an abnormal situation. If this happens, you should clear this issues in the forums and make any decision be explicitly stated there. If PMs decide to leave something for final fixes it should be clearly stated there. Same if some requirement is left out of scope.
What do you if the environment is buggy or unstable?	You should involve PMs as soon as possible to fix these issues. This is a common ground for timeline extensions, so if these problems delayed your work, feel free to ask for it.
How do you optimize your forum questions to minimize any delays?	The sooner you ask the better. Try to be very concise in your questions. It's a good practice to enumerate all those questions you expect an answer to avoid something to be left without a proper response. Be sure to carefully read the forums before posting to avoid unnecessary redundance.
I was scored down incorrectly, how do I appeal?	Don't take anything reviewers say for granted. They also make mistakes. If you were scored down incorrectly, try to explain why you think you deserve another score and be as detailed as possible. If your point still gets rejected by the reviewer after appeal response you can contact PM to make a final rule about that issue.

XV. Conclusion

That concludes this assembly tutorial. You've registered, evaluated, developed, tested, submitted, been reviewed, appealed, won, fixed, and finally submitted once again. You've earned your payment. Again, congratulations. What better way to celebrate than finding another project to register for and doing it all over again?