Simulator Development
From RoboCup
Contents |
Development policy
Developers are encouraged to use the librescue and rescuecore libraries whenever possible. Librescue and rescuecore provide basic functionality for developers using C++ and Java respectively. Both libraries provide implementations of the communication protocols and encapsulate world data in an object-oriented manner.
Software officially supported by the RoboCup Rescue Simulation League is managed by sourceforge.
Elements of the software that need work are listed under "Tasks" on the sourceforge project website. If you want to add something to this list then please use the "Feature Requests" mechanism provided by sourceforge.
Towards Version 1.0
Please take a look at the Version 1 discussion page to see what progress has been made towards a full version 1.0 of the simulator.
Compilers and tools
All code should be compilable with either gcc4 or Java 1.5. There are known incompatibilities between gcc3 and gcc4 so developers should use gcc4 when possible. Similarly, the Sun JDK is the reference environment for Java software.
Developers should include a Makefile so users can compile the software easily.
Release policy
Releases are made when new features are implemented or when major bugs are fixed. Each release has major, minor and maintenance version numbers. For example, version 0.49.8 is the 8th maintenance release of version 0.49.
Major version numbers are incremented when significant architectural changes are made to the software and different major versions will generally be incompatable.
Minor version numbers are incremented when new features are introduced.
Maintenance numbers are incremented as bugs are fixed.
Use of git
The main repository has been moved from subversion to git. For general information on how to use git please consult the git website or kernel.org.
Checking out the repository
Once you have git installed on your system use the following command to get a copy of the latest code:
git clone git://roborescue.git.sourceforge.net/gitroot/roborescue
This will create a local copy of the repository in the current directory. There are a number of branches in the main repository:
- master: This branch contains the latest stable version of the software. In this branch it is expected that there are no failing units tests, checkstyle issues or findbugs warnings.
- experimental: This contains "bleeding edge" software, such as new simulators. This branch may contain checkstyle issues or findbugs warnings but junit tests are expected to pass.
- Version branches will be created once version 1.0 is ready.
If you want to switch to a particular branch use:
git checkout origin/<branchname>
You probably don't need to worry about server-side branches unless you are fixing a particular issue in an old version of the simulator, or you want to develop your agents against a particular release. In that case, you should probably just download the pre-packaged release from the sourceforge website.
Submitting changes
Once you have finished making a change you should create an email bundle of your local commits with git-format-patch:
git-format-patch origin
Gzip and email the output to cls@ecs.soton.ac.uk for review and integration into the main repository.
Please try to make each individual commit a small functional unit. You can submit a number of these commits in a single patch, but try not to submit commits that are half-complete. Use git rebase --interactive to squash a series of related commits into one before submitting the changes.
Recommended work pattern
I suggest the following pattern of work, assuming you have already obtained a copy of the repository with git clone
-
git checkout -b my_working_branch_name origin/master - Hack away
-
git commit -a -m "Made lots of changes and wrote a meaningful commit message" - Hack a bit more
-
git add my/changed/file my/changed/file-2 -
git commit -m "Made some more changes and wrote another meaningful commit message" -
git fetch -
git rebase origin/master - Fix any conflicts
-
git-format-patch origin -
tar -czf my-patch-name.tgz *.patch - Upload my-patch-name.tgz to sourceforge
Make sure you use meaningful commit messages. I recommend committing often during development and using git rebase --interactive to squash commits into one when your feature or bugfix is complete. It's also worth running git fetch followed by git rebase origin/master reasonably frequently (maybe once a week, or more if you see many commits send to the mailing list) to make sure your local branch follows the main repository closely.
Reporting bugs
Bug reports should be submitted to sourceforge. Please include the following details when making a bug report:
- A detailed description of the problem including instructions on how to reproduce it
- Include relevant config files or code snippets
- Which version of the software contains the bug
- Your operating system and compiler version
- Any workarounds
If you suspect you know how to fix the bug then also include this information, or, better still, fix it yourself and submit a patch.
