Power TAC development policies

License
Project code is licensed under the Apache License, version 2.0. All modules, as well as other code-like artifacts, need to contain a license notice at the top in appropriate comment format. For Java/Groovy modules, the notice shall read as follows: /* * Copyright 2009-2010 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an * * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, * * either express or implied. See the License for the specific language * governing permissions and limitations under the License. */

Traceability
Project members need to be able to find answers to questions such as
 * Why is this code here? Is it still being used?
 * What is this code supposed to do?
 * Who wrote this mess? When was it written?


 * Who has changed this code since it was written? Why?
 * Has this code been tested? What tests does it pass?

Writing code
Code is being written in a number of languages, including Java (the agent), Matlab and Python (analysis tools), PHP and Python (the experiment-management tool), and shell scripts. Here are some general principles. For Java coding, please follow our Java coding guidelines.


 * Consistency and readability are at least as important as performance, except in very unusual circumstances. If you find yourself in one of those circumstances, please include commentary that explains why you felt a need to diverge from project standards.
 * Please don't invent idiosyncratic names for domain concepts that might appear in multiple places. Either use a term from the Project Glossary, or add an entry if the concept you are trying to express is not yet in the glossary. Be prepared to refactor names if the team agrees on a change in terminology.
 * Always include the standard project copyright header (TBD).
 * For small standalone tools (shell scripts, Python programs), include a header that explains how to use your code.
 * For all other code, include a header comment that explains what the code is, what role it plays, and how to use it.

Package (namespace) usage
The top-level package name for all Power TAC code will be org.powertac. Because of the large number of institutions involved in development, it makes no sense to use the names of individual institutions to name packages.

Testing
As far as possible, all non-trivial modules will be accompanied by test code. Note that in both the server and the agent framework, the test hierarchy is separate from the code hierarchy.

Issue tracking
For issue tracking use the following sites:
 * When you see an issue, report it on Launchpad:
 * Power TAC prototype server: https://bugs.launchpad.net/tacenergy
 * Power TAC client framework: https://bugs.launchpad.net/tacenergydemo
 * As you work an issue, update the bug to track your progress, and make sure all your commits include the string #nn where nn is the Launchpad bug number. When you commit a fix, make sure to do it like this:  where nn is the Launchpad bug number.
 * When you open an issue that involves non-trivial changes to existing code, create a branch.
 * When you complete an issue, update the bug.

Use of the bazaar repository

 * Create an account on Launchpad and ask to be added to the Launchpad TAC group by contacting the group owner
 * Get familiar with Bazaar and read about how to use Bazaar with Launchpad
 * be sure to identify yourself once to Bazaar with the E-Mail address you used to register with Launchpad, e.g.  This ensures that changed you commit will be associated with your Launchpad user account and page.
 * Anything bigger than minor changes should be done on a branch. Learn how to use bzr branches. It is up to you if you want to use a local branch or store your personal or team branch on Launchpad. Here is an example if you want to have your branch on Launchpad and are a member of TAC:








 * If you are not a member of TAC and want to store tacenergy as a personal branch:








 * When committing changes, describe them and include a bug number if possible. The change descriptions in bazaar are the primary record of changes to MinneTAC - who made changes, what was changed, and why. Don't commit anything without an explanation in the commit message.
 * Don't check in stuff that breaks. It's not enough that it compiles. It should pass the unit tests, and it should be able to run a competition.
 * Don't check in "derived" files - data files, compiler outputs, etc.

Merging

 * When you are finished working on a branch, this is what you should do:
 * Go to your branch on Launchpad and click on "Propose for merging"
 * As target branch, type in
 * Click "Propose Merge"
 * TAC-Members will be asked to review your code, once that happened you will receive an E-Mail
 * If you get approval, merge your code using