Written by Ulrik Sverdrup <ulrik.sverdrup@gmail.com>
Thursday, 22 November 2007

  Freeciv Contrib files tracking

This project tracks contrib files for the free empire-building game Freeciv.
Contrib files are user-created files and other files that are not part of
the main distribution.


  File hierarchy

See the file preconfiguration.README for the meaning of different files.

Currently we are tracking contrib files that are not soley about graphics,
but have a textual content meaning and make sense to be progressively
patched and developed. This means scenarios, maps, rulesets and to some
exent tilesets. Other miscellaneous content that fits to these criteria is
also welcome!


  Repository structure

There are some scripts present in the repository to ease "building" the
distribution version from the tracked files. These files should exist in all
branches of the repository.

  Branches
  
* common: A developing ground for common files that span all versions of
  contrib files. Examples are preconfiguration.README and similar documents,
  general contrib policy and information documents.

* 2.1: Each major freeciv version will have its branch in the repository.
  They might initially be pretty empty, but it is welcome to start a porting
  effort by introducing new files in any old or new branch.

* master: master will track the CURRENT stable freeciv version
* dev: (possible) will track the current developement version of freeciv

* meta: (possible) A standalone branch (meaning it has no files in common
  with the above) that will contain meta-information

  Merging

The merging order should be: Changes that go into common should be (and
should be able to) be merged updwards into relevant freeciv release branches
(2.1, 2.2 etc). 2.1 should be merged upwards into master.

The stable branches (2.0, 2.1, 2.2 etc) are not intended per se to be merged
later on; they should be branched off the latest version when a new version
arrives: 'dev' will become the new stable branch (for example 2.3) and a new
dev will be created, master will track the old dev etc.


  Working with the repository
  
First, clone the repository

git clone git://repo/url/here

check out the branch you are interested in (if it is not master/current stable)

git checkout -b mytopic origin/dev

Make changes, edit. Test that they work. Commit to your local repository
"git commit -a" as much as you want.

if you have checked out with a username that allows pushing, you can push
your changes to upstream with

git push

else you will want to make a series of patches that you send to the
freeciv-contrib mailinglist

git format-patch origin/master..mytopic

   Maintainers

First, clone the git repository with a username that has push access

git clone git://repo/url/here freeciv-contrib
cd freeciv-contrib

To rebuild all distribution packages, run

./makedist.sh

this will create a subhierarchy in dist/

To rebuild a specific package you should be able to run

./makedist.sh path/to/package_or_pkg.spec

This will place the file in the current directory