An entire assignment is packaged as a single zip file with its own
internal subdirectory structure. 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 are divided into four groups. Required properties should always be provided for all assignments, all the time. Recommended properties expected for all assignments, but stingy or lazy contributors may still fail to provide them (we'll bug them, but we won't force them). Optional properties are not required. We'll give contributors a chance to provide them, but won't nag. We expect that many assignments won't provide some or all of the optional properties. Finally, repository properties are provided automatically by a third party, typically when an assignment is uploaded to some service. These properties are not intended for direct editing by end users or contributors, but are provided in downloaded assignments for informational purposes, and to aid in tracking the relationships between modified/adapted versions of assignments and their original ancestors.
This page lays out the required, recommended, and optional fields that are present in each assignment metadata file. You can view these properties in action in the following two example properties files:
verbose-assignment.properties (contains descriptive embedded comments)
assignment.properties (no embedded comments, still formatted for readability)
title = A Tetris-playing Robot
A title for this assignment, provided by the contributor. Like a paper title, it should be as descriptive as possible. However, titles are not presumed to be unique.
synopsis = Build a class that represents an automated tetris player, and \
that can be run inside a pre-provided tetris game with a full GUI \
(no GUI programming involved).
A brief, one- or two-sentence description of what this assignment is about. In other words, a mini-abstract, longer and more informative than the title but still very concise. Let's say, approximately 30 words or less.
programming.language=c++
The target programming language for this assignment (case-insensitive). Use the common language name if the assignment (e.g., "java", "c++", "python", etc.).
author1.name.first = Stephen H. author1.name.last = Edwards author1.email = edwards@cs.vt.edu author1.url = http://people.cs.vt.edu/~edwards/ author1.affiliation = Virginia Tech, Dept. of Computer Science author1.phone = +1 540 231 5723
Basic contact information. Can be repeated as many times as necessary with different numeric suffix to cover the number of authors/contributors involved.
languages = en
A comma-separated list of one or more languages in which this assignment's files are written. Values should conform to RFC 4646. If no value is given, then "en" is assumed.
Individual files within the assignment should use one language only, but multiple translations within the assignment are fine. Note that the first entry in this list is considered the "primary" language for this assignment, and it is expected that all supporting files will be available in that language. Other languages in the list would then imply that translations for some or all of those files in the given language would also be provided as part of this assignment.
copyright = (c) 2008 Virginia Tech Department of Computer Science
The copyright holder and date. This can be automatically filled in when the assignment is submitted (default == current year and contributor).
license = Creative Commons Attribution-Noncommercial 3.0 United States License
The name of the license under which rights to use this assignment are granted. If omitted, the assumption is "all rights reserved by the copyright holder". When a new assignment is uploaded, we can suggest this creative commons license as the default. We can also provide a drop-down list of the most common choices, including the creative commons choices and approved OSI open source licenses.
license.url = http\://creativecommons.org/licenses/by-nc/3.0/us/
The URL under which the full text of the license is available on-line.
keywords = GUI, JUnit, TDD, test-first coding, \
test-driven development
A comma-separated list of keywords or tags provided by the contributor.
type = program
An element that gives one of the following values, characterizing the type of deliverable the student will produce. Examples include: program, class, method, function, block, statement, declaration, etc.
topics = recursion, parameter passing, method decomposition
An optional comma-separated list of keywords or tags intended to identify the knowledge content that is the focus or context of the assignment, where appropriate. Be specific. This list not only explains what the goals of the assignment are, but also implies what prerequisite knowledge students must have before attempting this assignment.
If possible, CC2001 (or newer) knowledge units can be used in this spot, although contributors are also free to use more generic terms, including any other appropriate labels they feel will be recognizable by others.
builder = CppTddPlugin
Specifies the name of a program builder used to compile student solutions. A controlled, but extensible vocabulary will be used, but defined later. At a minimum, Web-CAT plug-in names can be used. For assignments that include a "frame", the builder needs to know how to interpret the frame correctly.
tester = CxxTest
Specifies the name of a program runner used to execute student solutions on test data. A controlled, but extensible vocabulary will be used, but defined later. At a minimum, Web-CAT plug-in names can be used.
abstract = This is a cool game assignment that motivates students ...
A free-form text property that provides space for a one- or two-paragraph abstract of what this assignment is about and why you would want to use it. It supplements the title and one-sentence synopsis.
goals = This assignment is designed to allow students to practice \
writing recursive ...
A free-form text field that allows the contributor(s) to explain the educational goals and learning objectives of the assignment in prose form, as a supplement to the "topics" property.
potential = This assignment lends itself well to contests, where \
student solutions are played against each other. This is an \
excellent way to increase engagement. Consider offering extra \
credit for achieving different levels of performance, or for winning \
a contest.
A free-form text field that allows the contributor(s) to suggest ways that an assignment can be extended, adapted, enhanced, or improved. This is a way to capture "future work" ideas, and is explicitly intended for describing "features" that are not part of the assignment as written, but that could be created by others.
info.url = http\://courses.cs.vt.edu/~cs1705/assignments/tetris.html
A URL for a page/site maintained by the contributor with more information about this assignment. This is another way for contributors to publicize their own work and efforts related to this and other assignments, if they want. It is purely optional.
programming.language.vendor = GNU g++
If this assignment requires a specific implementation of the target programming language, specify it in this optional attribute.
programming.language.version = 3.5+
If this assignment requires specific version of the target programming language, specify it here. Use a suffix of "*" to indicate any version that begins with the given prefix (e.g., "3.5*" matches 3.5, 3.5.1, and 3.5.7, but not 3.6 or 4.0), or "+" to indicate any higher version (e.g., "3.5+" matches 3.5, 3.5.1, e.5.7, 3.6, and 4.0, but not 3.4.9).
course = CS1, CS1705: Introduction to Object-oriented Development I
Identifies the academic course(s) for which this assignment is targeted. Can be a comma-separated list. Where possible, complete course numbers and titles should be provided, although contriutors can also use generic terms (like "CS1") or tags (like "introductory") or any other appropriate label they feel will be recognizable by others.
estimated.experience = 3
Gives an estimate of how much experience a student should have in order to tackle this assignment. The estimate is approximate months of experience, where 0 means no programming experience of any kind, 12 means the equivalent of a complete year of academic study in the target programming language, and so on. Obviously, different curricula include different topics at varying times, so this estimate presumes that the necessary prerequisite knowledge has been covered reasonably. When in doubt, use the position within your course, and the experience level of students entering your course as a guide (i.e., "3" is a good estimate for an assignment that might be used in the middle of a one-semester introductory course, while "15" might be appropriate for an assignment used in the middle of a second-year course, for example).
estimated.time = 2 weeks
Gives an estimate of how many hours (or days, or weeks) students should be given to work on a solution--normally, the difference between when an assignment is handed out and when it is due. A laboratory assignment might have an estimated time of 1 or 2 hours, while a longer programming assignment might have a value of 1 or 2 weeks.
The format for this value is an integer followed by a unit name. The allowed unit names are: hour, hours, day, days, week, and weeks.
estimated.size = 250
Gives an estimate of how many lines of code (not including comments or blank lines) students are expected to write to produce a 100% correct solution.
repository.id = catspace.web-cat.org:1234 ab47
A globally unique identifier for this assignment, generated by the repository or service to which the assignment is uploaded. The property also includes a rudimentary checksum-style hash code for error detection and tamper resistance.
repository.version = 4b1.2
A generated version number for this assignment. The versioning scheme is really a way to track both changes to an assignment by the original author and derivations/modifications/adaptations by others who wish to contribute their work back to the community. The version number is a sequence of an odd number of positive integers separated alternately by "b"'s and periods.
The intent is that the very first submission of an assignment ever by the original contributor is version "1". The contributor (or any of the individuals listed as authors, who are all "contributors" from this perspective) can make changes to an assignment and re-upload at any time. This simply increments the version number, creating versions "2", "3", and so on.
An independent party may download and modify/customize and assignment, and then wish to share this version. When they do, they are effectively creating a branch from the original. The version number for their new contribution would be the version number of the source they modified, with an appended branch number (i.e., a repository-assigned version number indicating which branch from the original this is), followed by a version number for this branch.
In other words, suppose assignment A had been submitted (version 1), and then revised by the original author three times (now version 4). Now suppose a new contributor downloads the latest version (4) of assignment A, modifies it, and then wishes to contribute it back. This would be the first derived offshoot, or branch, from A's version 4, which we can call 4b1. Further, this would be the first version of this derived work, so its full version number would be 4b1.1.
The author of this derived work could then make a few more changes and submit again, to create version 4b1.2. In the mean time, yet another individual could also modify assignment A and submit his completely independent variation, which would be numbered 4b2.1. Of course, the original author might also make a change to create version 5.
Finally, another interprising instructor might take version 4b1.2 and create her own distinct flavor, which would then be 4b1.2b1.1. In principle version numbers could be an arbitrarily long sequence of branch number/version number pairs following the root version number. Each branch number/version number pair in the chain is written
bNN.MM, where the "b" and "." are merely punctuation,NNis the branch number, andMMis the version number.
repository.root.id = catspace.web-cat.org:179 cc55
The repository.id for the original assignment this one was derived from--i.e., the "root" of the variant/derivation tree to which this assignment belongs. If this assignment is not derived from any other, then the repository.root.id = repository.id.
repository.url = http\://catspace.web-cat.org/assignment/1234
A publicly accessible URL where people can view information about this assignment, typically provided by some repository/service to which this assignment has been uploaded.
repository.history =
A human-readable change history summary for this assignment. If the repository/service hosting this assignment allows contributors to briefly describe changes when they upload modified/customized assignments, then a consolidated presentation of the change history associated with this particular version can be generated here for informational purposes.
repository.acl = SomeGroupName
A comma-separated list of identifiers used to enforce access control restrictions for this assignment at its home repository/service, provided purely for informational purposes. Changes to this field should be made directly through the repository interface's access control features.