An entire assignment is packaged as a single zip file with its own internal subdirectory structure. At a minimum, such a file contains an assignment writeup and a simple metadata file with information about the assignment. More complex assignments may contain many additional supporting files, as needed.
Much of the info we expect for people to provide can also be handled by file naming/placement conventions. Here is an outline of the organization of the required/optional elements.
Also, note that all files are text files (encoded using UTF-8). Presumably, we should handle contributions with Unix, Mac, or Windows- style line ending conventions and then normalize them. We should probably also provide for downloads to be translated to a given platform's line ending conventions (through user preferences or browser request settings).
An assignment also has a designated primary language, which is identified in its metadata. Optionally, multi-language support in the form of translations may be provided as well.An assignment upload is a zip file that includes an "assignment.properties" file at its root. Other files written in the primary language are also included in the root of the zip file, or in subdirectories off the root. The basic structure looks like this:
/assignment.properties /assignment.html ... other files as needed ...
The assignment's metadata is stored in a Java properties file
called assignment.properties stored in the root of the zip
file. For more information about Java properties files, you
can read the Wikipedia
article on properties files or the
Sun
Javadoc for the Properties class
(look at the information on the load() method).
The properties file contains the assignment's title, author, programming language, prerequisites, and more.
This properties file should contain the fields defined in the assignment metadata file structure.
When most people think of an assignment, they think first of the assignment's writeup, which might also be called an assignment specification, an assignment handout, or instructions for the student. Here, we will use the term writeup.
An assignment contains a writeup as a single file in one of the following formats:
HTML is the preferred format for assignment writeups, if available. A single HTML file should be used, if possible. Avoid external style sheets and javascript resources. Simple vanilla HTML should be used for maximal reuse by others. In other words, don't use fancy multi-column layouts, custom fonts and colors, background images, or other fancy window dressing. Also, please avoid HTML generated by Microsoft Word.
If your HTML uses extended characters (outside the US-ASCII 7-bit set), please be sure to put an appropriate content type specification in the document's <head>, like this example for UTF-8-encoded HTML:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
If your HTML document includes images, you can place them in
an images/ folder within the root of the zip file.
Please use relative paths within the HTML file.
If you prepared your assignment writeup using Microsoft Word or another word processor, instead of providing an HTML version, please provide an RTF version (Rich Text Format). From Word, use the Save as... command from the file menu and select the RTF format for your file. Keep the formatting within your writeup as simple and clean as possible.
If you do not have an HTML or RTF version of your assignment writeup, you can provide a plain text version instead. If you are using an extended character set for your text, please use UTF-8 encoding.
Each assignment has a primary language (such as English, Spanish, German, etc.) defined in its metdata file. All of the assignment's resources are presumed to be provided in this primary language.
In addition, you can provide translated versions of any or all of the assignment's files--the writeup, any sample solutions, any reference tests, etc.--in one or more secondary languages. The secondary languages for which your assignment's files are available are also listed in its metadata file.
All translated assignment files in secondary languages should be placed in a subdirectory within the zip file named after the language in which the file is written. Languages (and their corresponding subdirectories) use short (usually two-letter) names that conform to RFC 4646. That means the top-level of a multi-lingual upload might look like this:
/assignment.properties /assignment.html /... other files ... /de/assignment.html -- subdir for files written in German /de/... other files ... /en/assignment.html -- subdir for files written in English /en/... other files ... /fr/assignment.html -- subdir for files written in French /fr/... other files ... /se/assignment.html -- Swedish ... /se/... other files ...
In addition to the assignment writeup itself, many assignments include a variety of additional supplementary files used in an assignment. These are typically added to the zip file in an appropriate subdirectory based on the following conventions. Secondary language translations of supplementary files are placed in an identical subdirectory structure within the corresponding language's directory in the zip file.
This directory should be provided if there are any program source files that must be available to the student for importation by their solution code. Examples include C or C++ header files, Perl modules, or library modules for interpreted languages that are typically imported in source form (e.g., PHP, Python, Ruby, Scheme, Prolog, etc.).
Place the necessary source files in a subdirectory structure appropriate for the target programming language within the include/ subdirectory. Also provide a readme.txt file describing where the latest version of these source files can be found on the internet, as well as links to any associated on-line documentation.
If the source files in this directory are provided under a different license than the assignment itself, please include an appropriate license.txt file in this directory describing the terms. Note that the license must grant redistribution rights in order for the files to be included in your assignment upload.
When necessary source files cannot be included as part of the assignment due to licensing restrictions, include an explanation in the readme.txt describing what source files are needed and where they can be obtained.
This directory should be provided if there are any compiled program
files or libraries that must be available to the student for
linking by their solution code. Examples include Java jar files,
C or C++ libraries, etc. If the assignment is designed for a programming
language that uses platform-independent binaries, then binary library
files can be included in this directory. For languages that use
platform-specific binaries (i.e., natively executable object code),
please provide the source code used to generate the necessary library
files in a lib/src/ subdirectory. Include an appropriate
build script (such as an ANT build.xml file or a makefile) along with
the source.
Also provide a readme.txt file describing where the latest version of these binary and/or source files can be found on the internet, as well as links to any associated on-line documentation.
If the binary and/or source files in this directory are provided under a different license than the assignment itself, please include an appropriate license.txt file in this directory describing the terms. Note that the license must grant redistribution rights in order for the files to be included in your assignment upload.
When necessary binary and/or source files cannot be included as part of the assignment due to licensing restrictions, include an explanation in the readme.txt describing what files are needed and where they can be obtained.
If only platform-specific binary files are included in your assignment upload, please be sure to provide appropriate platform dependency information in the assignment.properties metadata file. If possible, provide links in the readme.txt file indicating where alternative binaries (or source) for other platforms can be obtained on-line.
This directory should be provided if a sample solution for the assignment is provided (strongly recommended!). Self-commenting source code in the assignment's target language should be used. Files should be arranged within this subdirectory the way a student's solution is expected to be organized.
If available, you may provide multiple sample solutions:
/solution/1/... /solution/2/... /solution/3/...
This directory should be used to contain any tests or test data files that you intend to be provided to students. These should be in a format appropriate to the style of the assignment and the intended target programming language. Examples include sample input text files (with or without matching expected output captures), sample input data files, JUnit tests, CxxTest tests, etc. The manner in which tests are to be executed is specified in the assignment's metadata file.
This directory should be used to contain any tests or test data files that you intend to be used by instructors or course staff, but that are not designed for public release to students. These should be in a format appropriate to the style of the assignment and the intended target programming language. Examples include sample input text files (with or without matching expected output captures), sample input data files, JUnit tests, CxxTest tests, etc. The manner in which tests are to be executed is specified in the assignment's metadata file.
This directory should be used to contain the "starting project" students should download and work from, if desired. The "starting project" may contain auxilliary files you wish for students to use (without having to write from scratch), template files you wish students to complete, or even required resource or data files that are necessary for a student to complete the assignment as described.
Sometimes, an assignment or exercise may require a student to write a code fragment instead of a complete program. This code fragment may be a single function or method, a single block of code, or even a single statement.
In this case, the student's submission is not really compilable on its own, and is instead simply a part of a larger whole. Assessment of correctness may then require that the student's work be placed inside a frame, kind of like a picture frame. The frame provides the environment in which the student's submission is intended to be examined.
This directory should be used to contain the "frame" used to assess the student's submission, if necessary. Normally, it consists of one or more program source files with clearly identified placeholders where the student's submission (or specific pieces of the student's submission) must be substituted in order to produce a self-contained compilation unit or module for the target programming language.