Skip to content

the contributor's handbook

Historical note

this was the contribution process while surplus was active. the repository is now archived.

expected details on development workflows? see the developer's handbook

which forge do i use?

as at the time of writing this documentation, i am actively using both https://github.com/markjoshwel/surplus and https://forge.joshwel.co/mark/surplus

use whatever is more comfortable to you. do you not like microsoft and/or have moved away from github? feel free to use https://forge.joshwel.co. don't want to make an account for either? did the forge implode and is down? okay! mail in a git patch at mark@joshwel.co

git workflow

  1. fork the repository and branch off from the future branch,
    or main if not available
  2. make and commit your changes!
  3. pull in any changes from upstream, and resolve any conflicts, if any
  4. if needed, commit your copyright waiver (see waiving copyright)
  5. submit a pull request (or mail in a patch)

Warning

this section is a must to follow if you have modified any unlicenced code:

  • top-level surplus files (releaser.py, etc)
  • surplus (src/surplus)
  • surplus Documentation (docs/)
  • surplus on wheels (src/surplus-on-wheels)
  • surplus on wheels: Telegram Bridge (src/spow-telegram-bridge)

Info

the command to create an empty commit is git commit --allow-empty

when contributing your first changes, please include an empty commit for a copyright waiver using the following message (replace Your Name with your name or username):

Your Name Copyright Waiver

I dedicate any and all copyright interest in this software to the
public domain. I make this dedication for the benefit of the public at
large and to the detriment of my heirs and successors. I intend this
dedication to be an overt act of relinquishment in perpetuity of all
present and future rights to this software under copyright law.

To the best of my knowledge and belief, my contributions are either
originally authored by me or are derived from prior works which I have
verified are also in the public domain and are not subject to claims
of copyright by other parties.

To the best of my knowledge and belief, no individual, business,
organization, government, or other entity has any copyright interest
in my contributions, and I affirm that I will not make contributions
that are otherwise encumbered.

(from https://unlicense.org/WAIVER)

for documentation contributors, if you have contributed a legally significant or have repeatedly commited multiple small changes, waive your copyright with the CC0 deed (replace Your Name with your name or username):

Your Name Copyright Waiver

The person who associated a work with this deed has dedicated the work to
the public domain by waiving all of his or her rights to the work worldwide
under copyright law, including all related and neighboring rights, to the
extent allowed by law.

(from https://creativecommons.org/publicdomain/zero/1.0/)

reporting incorrect output

Note

this section is independent of the rest of the contributing section.

different output from the iOS Shortcuts app is expected, however incorrect output is not.

the reporting process

historically, the process was to open an issue in the repository issue tracker and do the following:

  1. ensure that your issue is not an error of incorrect data returned by your reverser function, which by default is OpenStreetMap Nominatim. if you do not know what that means, then you are using the default reverser

  2. look at what counts as incorrect before moving on

  3. include the erroneous query this is the Plus Code, local code, latitude-longitude coordinate pair, or query string you passed into surplus

  4. include terminal output with the --debug flag passed to the surplus CLI, or with debug=True set in function calls

  5. explain how it should look instead, with reasoning if the error is not obvious

for reference, see how these historical issues were written:

what counts as incorrect

this should not be reported as incorrect:

iOS Shortcuts output:

Plaza Singapura
68 Orchard Rd
238839
Singapore

surplus output:

Plaza Singapura
68 Orchard Road
Museum
238839
Central, Singapore

the only difference is that surplus displays more information.

other examples that should not be reported:

  • the place name is different because the default geocoder returned a different name
  • the place data is wrong in OpenStreetMap or Nominatim
  • surplus includes extra address detail while still producing a logical address

report output when it does not make logical sense, repeats lines in a confusing way, orders address parts incorrectly, or is otherwise not correct in the traditional sense of a correct address.