Difference between revisions of "Wescamp.py Instructions"

From The Battle for Wesnoth Wiki
(Examples)
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Documented here is how wescamp.py works when -g (--git) is passed, so that it communicates with wescamp at github.com instead of wescamp-i18n at berlios.de.
+
Documented here is how wescamp.py works.
  
 
== Requirements ==
 
== Requirements ==
 
* Git
 
* Git
 
* Python (2.5 or above should work)
 
* Python (2.5 or above should work)
* Ssh keys so that git push doesn't require a password prompt
+
* Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
* Administrator rights on github.com/wescamp (for creating new repositories)
+
* Administrator rights on github.com/wescamp (if you need to create new repositories)
  
 
== Checkouts ==
 
== Checkouts ==
Like the svn invocation, with git, a directory per "version branch" is required. Unlike the svn version, you can't simply check out a single directory to do this.
+
Like the s­­v­­n invocation, with git, a directory per "version branch" is required. Unlike the s­­v­­n version, you can't simply check out a single directory to do this.
 
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.
 
The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.
  
Line 16: Line 16:
  
 
== Invocation ==
 
== Invocation ==
Invocation (for -u and -U) is the same as with svn, with the following differences:
+
* -u ADDON uploads a single add-on to wescamp.
* The -g/--git switch is required
+
* -U uploads all translatable add-ons.
* The -G/--github-login (with argument in the form of USER:PASSWORD) is required an upload would create a new repository on github. This is because a json API is used to create the new repository.
+
* -l lists all add-ons.
 +
* -L lists all translatable add-ons.
 +
* -c creates a normal checkout
 +
* -C creates a read-only checkout (doesn't require any github credentials)
 +
* -s SERVER is the hostname of the add-on server
 +
* -p PORT is the port of the add-on server
 +
* -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
 +
* -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
 +
** You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
 +
** This option can still be useful if no repositories are created. Github has a limit of 60 API requests per hour if you are not logged in, or 5000 if you are.
 +
* -b BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout
 +
* -B BRANCH can be used to specify the version we're syncing. This overrides the -w derived branch. It can also be used as a fallback for when -p isn't given, but there are some issues with that (see below).
 +
* -e ERROR_LOG can be used to specify a file to save all errors to. This is useful for log storage and automated runs.
  
 
== Examples ==
 
== Examples ==
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c -g
+
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c
 
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.
 
This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.
  
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown -g
+
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown
In this case a checkout of the Invasion_from_the_Unknown-1.10 repository already exists in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/
+
An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.
  
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -g -G USER:PASSWORD
+
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD
In this case the directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github.
+
The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.
  
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -g -G USER:PASSWORD
+
  ./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G longhexadecimalstringthatisanoath2bearertoken
 
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.
 
Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.
 +
 +
== Issues ==
 +
GitHub has a 60 requests per hour limit if you do not pass authentication info. If you do, this limit is raised to 5000. It is possible to hit the 60-requests limit doing read-only operations, so it's a good habit to always use -G.
 +
 +
The -B option will override the -w derived github version just fine, but doesn't work well as a addon-server version. This is because addon-server development version uses the development branch version (e.g. 1.11), while on github we use the version of the stable it will become (e.g. 1.12). So when using -B, you should still use -p.
  
 
== Notes ==
 
== Notes ==

Revision as of 19:30, 10 May 2013

Documented here is how wescamp.py works.

Requirements

  • Git
  • Python (2.5 or above should work)
  • Ssh keys so that git push doesn't require a password prompt (for everything except -C, which uses a read-only checkout)
  • Administrator rights on github.com/wescamp (if you need to create new repositories)

Checkouts

Like the s­­v­­n invocation, with git, a directory per "version branch" is required. Unlike the s­­v­­n version, you can't simply check out a single directory to do this. The -c/--checkout switch will check out a version directory for you, if it is properly named. The -U switch can make the checkouts as a side-effect.

A "version directory" is required to end in the version it's for, as this is currently the method used to identify the version. The following formats work:

/tmp/wescamp/1.10
/tmp/wescamp-1.10

Invocation

  • -u ADDON uploads a single add-on to wescamp.
  • -U uploads all translatable add-ons.
  • -l lists all add-ons.
  • -L lists all translatable add-ons.
  • -c creates a normal checkout
  • -C creates a read-only checkout (doesn't require any github credentials)
  • -s SERVER is the hostname of the add-on server
  • -p PORT is the port of the add-on server
  • -w WESCAMP_CHECKOUT specifies the directory of the wescamp checkout (or where it will be created)
  • -G USER:PASSWORD is your login to github. This argument is required if an upload would create a new repository on github. This is because a json API is used to create the new repository.
    • You can also use a github OAuth2 token instead of your username and password. This token must have the 'repo' scope.
    • This option can still be useful if no repositories are created. Github has a limit of 60 API requests per hour if you are not logged in, or 5000 if you are.
  • -b BUILD_SYSTEM_CHECKOUT can be used to specify a build-system checkout
  • -B BRANCH can be used to specify the version we're syncing. This overrides the -w derived branch. It can also be used as a fallback for when -p isn't given, but there are some issues with that (see below).
  • -e ERROR_LOG can be used to specify a file to save all errors to. This is useful for log storage and automated runs.

Examples

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp/branch-1.10/ -c

This makes a fresh checkout of all translatable 1.10 add-ons in the specified directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Invasion_from_the_Unknown

An existing checkout of the Invasion_from_the_Unknown-1.10 repository in /tmp/wescamp-upload/1.10/Invasion_from_the_Unknown/ is updated.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/1.10/ -u Era_of_Myths -G USER:PASSWORD

The directory /tmp/wescamp-upload/1.10/ exists, but there is no Era_of_Myths directory in it and neither is there an Era_of_Myths-1.10 repository on github. After this command it will be on github and a checkout will be in the directory.

./data/tools/wesnoth/wescamp.py -scampaigns.wesnoth.org -p15002 -w/tmp/wescamp-upload/branch-1.10/ -U -G longhexadecimalstringthatisanoath2bearertoken

Updates all 1.10 add-ons. If they are not yet on wescamp, a new repository will be created for them.

Issues

GitHub has a 60 requests per hour limit if you do not pass authentication info. If you do, this limit is raised to 5000. It is possible to hit the 60-requests limit doing read-only operations, so it's a good habit to always use -G.

The -B option will override the -w derived github version just fine, but doesn't work well as a addon-server version. This is because addon-server development version uses the development branch version (e.g. 1.11), while on github we use the version of the stable it will become (e.g. 1.12). So when using -B, you should still use -p.

Notes

If there's anything missing, please contact me. (AI0867)