Hacking on libgweather
======================

 + The development occurs in git:

     http://git.gnome.org/browse/libgweather

   For information on how to access GNOME git please read:

     http://live.gnome.org/Git

 + Please send patches as bug reports in GNOME Bugzilla:

     https://bugzilla.gnome.org/ (product libgweather)

   Your patch should be in unified diff form (the -u option to GNU
   diff). See also:

     http://live.gnome.org/GnomeLove/SubmittingPatches

 + Please try and send a patch against a recent version of this package.
   Patches against git master are most preferable.

 + Don't commit any but the most trivial patches without approval.

 + Exceptions to this are:

   - Translators may commit basic i18n related patches to the build
     setup.
   - Build sheriff are welcome - in accordance with the relevant build
     sheriff constraints.


Adding new weather sources
==========================

To add new weather sources, a number of requirements must be considered:
- the API should be documented
- access to the API can require the use of a freely available application
  token ID. See the requirements below.
- there must not be hard usage limits, or they must be high enough not to
  cause disruption with weather support being builtin to the OS/desktop
- the requests must be made over HTTPS, or an equivalent, encrypted network
  connection.
- the result of requests must be machine parseable, and the parsing code
  must have unit tests to prevent regressions, and make it easy to root-cause
  crashes
- the user’s privacy must be maintained as much as possible, see section below
- the user’s bandwidth must be preserved where possible, with the server offering
  enough information to avoid downloads through libsoup, our HTTP library.
- the data gathered can require a attribution (in which case the patch must
  contain code to implement this) and if restricted to non-commercial usage,
  must have a comment mentioning that fact in the GWeatherWeather API documentation
- finally, a working and applicable patch must be provided

Privacy
-------

The user’s privacy must be maintained as much as possible:
- don’t include unnecessary detail in requests
- don’t allow fine-grained location tracking
- don’t include other identifying information in the requests if possible
- service must have a data usage policy that's reasonable compared to
  equivalent services, eg. not use requests as a way to feed into user tracking
  for an advertisment business

Application token usage
-----------------------

Not using tokens is preferable, but some data sources don't offer the option.
There are a number of requirements for those tokens:
- One should be provided in the patch for testing purposes, and be easily
  overridable by distributions wishing to have a separate identifier and limits
- The test token should have high enough limits that you're reasonably confident
  that lots of people running `make check` won’t cause the token to be revoked
  and break everyone’s tests
- Instructions on how to get a token for the application must be provided