Contributing

👋 Hello there! 🎉 Thanks for taking the time to contribute!

Seen something outdated or plain wrong? Spotted a typo somewhere? Think something could be better translated, or want to translate the whole deck into a new language? Awesome! 💯 Let us know right away by opening a new issue.

Contributor's guide

Ready to start working on an issue? Here is what you need to know.

If you're new to contributing on GitHub, read this guide first.

The deck is managed with Brain Brew, a deck manager that allows transforming Ultimate Geography back and forth between its CrowdAnki JSON representation and a format that is easy for humans to read, modify and version-control (currently CSV). This means that one can edit this deck either here, in this repository, or in Anki itself.

Brain Brew and its dependencies are managed with Pipenv. Running Brain Brew inside a virtual environment guarantees that is not hampered by individual setups.

The content of the deck is stored in multiple CSV files under src/data. The main file is main.csv. Each row corresponds to a note and each column to a field.

Translated fields, such as Country or Capital info, have their own CSV files called derivatives, in which each column corresponds to one language. The Country field is used to map rows in the derivatives with notes in main.csv. The mapping is not necessarily one to one: if a note has no capital (e.g. because it's a water body), then it must not appear in capital.csv.

Getting started

Fork and clone this repository on your machine.
Install Python 3.7
- During the installation, make sure to install pip (it's optional) and to tick Add Python 3.7 to PATH.
Install Pipenv with pip install pipenv.
- If the pip executable is not available, try pip3 install pipenv instead.
In the root directory of your fork, run pipenv install to install Brain Brew and its dependencies in a new virtual environment.
You can now run this deck's Brain Brew recipes with pipenv run brain_brew run recipes/<filename>.yaml.
- Alternatively, run pipenv run build to build the deck for Anki with the source_to_anki.yaml recipe.

Brain Brew recipes

Source to Anki

pipenv run brain_brew run recipes/source_to_anki.yaml

This recipe builds the deck from source in a format that can be imported into Anki with the CrowdAnki add-on. More precisely, it generates every possible version of the deck (i.e. standard + extended, in every language) into sub-folders inside the build folder. Each of these sub-folders includes a CrowdAnki JSON file and all of the deck's images.

On first run, this recipe generates all the missing files and folders in the build folder, logging warnings in the output. Upon subsequent runs, the warnings disappear.

Anki to Source

pipenv run brain_brew run recipes/anki_to_source.yaml

This recipe allows editing the English standard or extended deck in Anki, and then pulling the changes into the CSVs. Other languages are currently not supported. It also does not support editing the note model, card templates, deck description, etc. -- only the content of the notes.

Make your edits in Anki.
Export the deck with CrowdAnki into the build/Ultimate Geography [EN] folder (even if you've edited the extended deck).
Run pipenv run brain_brew run recipes/anki_to_source.yaml.
Any new media will be placed at the top level of the src/media folder and will need to be moved into the appropriate sub-folder.

How-to's

To add a new note to the deck, add one row to main.csv, guid.csv, and any of the derivative CSVs as needed. Don't fill in any of the GUIDs in guid.csv -- they will be generated automatically by the source_to_anki.yaml recipe.
To change the Country field of a note, change it in main.csv, guid.csv, country.csv, and any other derivative CSV in which the note appears.
To add a new translation, add a new column to each of the CSV files and name them as follows: [field name]:[language code] (e.g. country info:fr, all lowercase). In most cases, the language code should match the Wikipedia subdomain for that language (e.g. https://fr.wikipedia.org/).

When editing guid.csv please try to avoid using a spreadsheet, if possible, and instead use a text editor (e.g. notepad) since spreadsheets mangle some of the GUIDs that start with = signs.

Adding new fields (e.g. population, currency, etc.), the most heavily requested change to the deck, will soon™ be solved using Brain Brew, by combining separate repositories. Stay tuned.

Content inclusion rules

In order for a geographical entity to be included in the deck, it must:

belong to a well-defined, well-sourced list of entities of a common type (e.g. sovereign states, seas, etc.);
meet the inclusion criteria that apply to entities of this type.

Political geography

Inclusion rules for political entities are documented and put into use in political-entities.xlsx. They were discussed in #137, #221, #306, #312 and #361.

A political entity can be included either fully (map, capital, and flag) or partially (with only a map). In the rare case where a political entity belongs to more than one of the below categories, it will only be considered in the first category of which it's a member.

Sovereign states

Source: https://en.wikipedia.org/wiki/List_of_sovereign_states
All fully included, regardless of UN membership status or recognition by other states.

Dependent territories

Sources:
- https://en.wikipedia.org/wiki/Dependent_territory
- https://en.wikipedia.org/wiki/Countries_of_the_United_Kingdom
Specifically, inhabited dependent territories.
Criteria for inclusion with map: population >= 15,000 OR area >= 1,000 km2
Criteria for inclusion with map, capital, and flag: (population >= 15,000 AND area >= 1,000 km2) OR population >= 100,000

Autonomous islands

Source: https://en.wikipedia.org/wiki/List_of_autonomous_areas_by_country
Specifically, insular autonomous territories.
Criteria for inclusion with map: population >= 100,000
Capitals and flags never included.

Transcontinental overseas territories

Source: https://en.wikipedia.org/wiki/List_of_transcontinental_countries
Specifically, inhabited territories located on a different content than their mainland.
Criteria for inclusion with map: population >= 100,000 AND distance from mainland >= 300 km
Capitals and flags never included.

Enclaves and exclaves

Source: https://en.wikipedia.org/wiki/List_of_enclaves_and_exclaves#Semi-enclaves_and_semi-exclaves
Specifically, inhabited full or semi land enclaves/exclaves.
Relevant sections:
Criteria for inclusion with map: population >= 100,000 AND distance from mainland >= 300 km
Capitals and flags never included.

Physical geography

Apart from continents and oceans, inclusion rules for physical entities are documented and put into use in physical-entities.xlsx. They were discussed in #137 and #346.

A physical entity can only be included partially, with only a map.

Continents

Source: https://en.wikipedia.org/wiki/Continent#Number
Specifically the seven-continent model but with the continent of Australia replaced with the world region of Oceania, as discussed in #345.

Oceans

Source: https://en.wikipedia.org/wiki/Ocean#Oceanic_divisions

Marginal seas

Sources:
- IHO, Limits of Oceans and Seas, 4th Edition (Final Draft), 2002
- IHO, Limits of Oceans and Seas, 3rd Edition, 1953 (adds Sea of Japan)
Specifically all water bodies defined in the above publications, with the exception of oceans, basins, straits, channels, passages, and the South China and Eastern Archipelagic Seas.
Criteria for inclusion:
- for water bodies defined in 1953: area >= 125,000 km2
- for water bodies added in 2002: area >= 500,000 km2
Area calculations are based on the IHO's 2002 definitions.

Straits

Sources:
- IHO, Limits of Oceans and Seas, 4th Edition (Final Draft), 2002
- Transit passage (adds Bab-el-Mandeb and Strait of Magellan).
Straits mentioned on the Transit passage article as being governed by an international convention are included.
Groups of straits and their constituents are excluded, namely the Danish straits and Turkish Straits.
Criteria for inclusion: is transit passage OR (borders >= 2 states AND area <= 50,000 km2)
Area calculations are based on the IHO's 2002 definitions.

Channels and passages

Source: IHO, Limits of Oceans and Seas, 4th Edition (Final Draft), 2002
Criterion for inclusion: borders >= 2 states

Other water bodies

The deck currently includes a number of lakes for which inclusion rules have not yet been officialised. Other kinds of water bodies may also be included in the future (e.g. rivers).

Content guidelines

Country field

The correct name to use for a given country or territory in each language is not always clear. This usually occurs in two cases:

when the official name is changed but the old name remains more frequently used (in the media and in everyday conversation) - e.g. Ivory Coast vs. Côte d'Ivoire;
when the official name is simply shortened in everyday use - e.g. China vs. People's Republic of China.

Unless otherwise stated in the Translation sources section below, we take the title of the Wikipedia article for the country, in the language of the given deck. Alternative names may be mentioned in the Country info field, when relevant.

If the title of the Wikipedia article contains a parenthetical portion for disambiguation purposes, it must be removed, except in the very unlikely case that two countries share the same name in a given language — e.g. Saint-Martin (Antilles françaises) and Saint-Martin (royaume des Pays-Bas) in the French deck.

Country names must not be preceded by articles, particularly in gendered languages (French, German, etc.) unless Wikipedia indicates otherwise - e.g. United Kingdom, The Gambia. This rule also applies to the Flag similarity field, but not to other fields in which country names are used in sentences.

To understand the reasoning behind these decisions, see #181 (Wikipedia as source), #212 (disambiguating country names), and #157#issuecomment-549143860 (no gender articles).

Country info field

To help with memorisation and provide context while learning, this field may contain:

governance information - e.g. Overseas territory of the United Kingdom (Cayman Islands)
statehood information - e.g. Independent state claimed by Moldova (Transnistria)
alternative and former country names - e.g. Also known as Timor-Leste (East Timor)
in rare cases only, general knowledge information - see Melanesia for an example

The content of this field should be concise and consistent across notes. It may differ between languages, notably when dealing with alternative names.

Capital field

We use the capital(s) given in the infobox of the country's English Wikipedia article. This ensures consistency across languages and simplifies maintenance, as discussed in issue #416#issuecomment-821864712.

For spelling, unless otherwise stated in the Translation sources section below, we take the title of the Wikipedia article for the capital, in the language of the given deck. Alternative names may be mentioned in the Capital info field, when relevant.

If the title of the Wikipedia article contains a parenthetical portion for disambiguation purposes, it must be removed. The Capital hint field is used instead for disambiguation.

If multiple capitals are listed in a country's infobox, the following guidelines apply:

If the first capital is followed by a qualifier such as "official", "constitutional", "de jure", "claimed", or "political", it must be used alone in the Capital field. The Capital info field must then be used to detail the status and/or role of every capital - e.g. While Dodoma is the official capital, Dar es Salaam is the de facto seat of government.
If government branches such as "executive" or "legislative" are the only qualifiers used, then the capitals must all be listed in the Capital field, separated by commas - e.g. Pretoria, Cape Town, Bloemfontein (South Africa). The Capital info field must again be used to detail the role of every capital.
If no qualifiers are provided at all, then the capitals must all be listed in the Capital field, separated by commas. A concise explanation should then be provided in the Capital info field.

Capital info field

As explained in the previous section, this field is typically used for countries with multiple capitals, to clarify the role and/or status of each capital, or to explain succinctly why the country has multiple capitals. In such case, the content of the field should be consistent across languages.

This field may also be used to provide alternative capital names and spellings, which may be language-specific.

Capital hint field

This field is used in notes that share:

the same exact capital - e.g. London (United Kingdom and England);
capitals with very similar names - e.g. Georgetown and George Town.

The hints appear on Capital - Country cards to avoid confusion or random guesses. They should convey as little information as possible to not give away the answers.

Flag field

This field must contain a single HTML image element pointing to the SVG image of a flag - e.g. <img src="ug-flag-seychelles.svg" />. The image must be placed in the media folder and named ug-flag-<country_name>.svg.

SVG flags are sourced from Wikimedia. We consider two possible sources for the flag: (1) the flag presented in the infobox of the English Wikipedia article for the country and (2) the primary flag presented in the English Wikipedia article for the country's flag. When both sources agree, we use the common flag; when they differ, we default to the state flag. We try to stay a few months behind edits in an attempt to avoid quick back-and-forth changes; in case of repeated back-and-forth changes, investigate reasons for the edit war, make a decision, document the decision in this document; review these decisions from time to time.

Discussion of some edit wars (in particular, some for Costa Rica, Peru, and Venezuela) can be found here.

The flag's source URL and licence must be documented in sources.csv.

The following guidelines apply to flag images:

The viewBox, width and height attributes are required.
The height must be set to 250 px (height="250") and the width adjusted proportionally.
Each flag must be optimised with SVGO.

If the name of a country appears clearly on a flag, a second version of that flag may also be provided, with the name of the country blurred out. The name should be blurred using Inkscape's Gaussian blur effect as explained in 587#issuecomment-1357163000. The blurred flag must be named ug-flag-<country_name>-blur.svg and placed in the media folder. A second HTML element must then be added to the Flag field before the existing HTML element. This allows the blurred flag to appear on the front of the country's Flag - Country card.

Flag similarity field

This field is used in the Flag - Country template.

In Anki, when you keep on confusing two flags, you can't put them side by side to learn their visual differences. The Flag similarity field works around this limitation by providing a concise description of the differences a flag has with another. It allows users to more easily learn to distinguish pairs of similar flags and perhaps come up with mnemonics to remember their respective countries.

A note's Flag similarity field contains a list of countries, each followed by a list of differences. For instance, the flag similarities for Iceland are written as follows: Norway (red background, blue cross), Faroe Islands (white background, red and blue cross). The list of differences must be precise, clear, and concise. Advanced vexillological terms should be avoided.

Flag similarities are always mutual: if flag A is similar to flag B, then flag B is similar to flag A. To determine whether two flags are similar enough to warrant mutual Flag similarity information, their differences must first be identified and classified. The following classification applies:

Critical differences (C)
- presence/absence of decoration - e.g. symbol, coat of arms
Major differences (M)
- same colours in different positions (e.g. two swapped, three cyclically permuted ("rotated"))
- decorations of different types in same position (e.g. symbol vs. coat of arms)
- decorations of same type in different positions (e.g. star(s) above/below band for Curaçao/Nauru)
Minor differences (m)
- slightly different colours (e.g. shade of blue, red vs. maroon, darker green)
- slightly different geometry (e.g. width, number of serrated edges for Qatar/Bahrain, size of canton)
- different decoration of same type in same position (e.g. different symbol, different coat of arms)
- decorations of same type in different amounts (e.g. fewer stars)
- decorations of same type with different colours (e.g. white vs. red stars for Australia/New Zealand)
Negligible differences (n)
- subtly different colours - i.e. ΔE < 30
- subtly different geometry

Two flags are then eligible for Flag similarity information when they respect the two rules below:

Their differences all fit in the above classification. For instance, France and Italy are not eligible because their left bands are respectively blue and green, and "different colours in same position" does not appear in the classification.
Their classified differences form one the following combinations:
- 1C 0M 0m {0+}n = one critical difference and any number of negligible differences
- 0C 1M {0–2}m {0+}n = one major difference, up to two minor differences, and any number of negligible differences
- 0C 0M {0–3}m {0+}n = up to three minor differences and any number of negligible differences

The Flag similarities wiki page lists the pairs of countries that have already been audited for flag similarities.

Critical, major, and minor differences should be listed in the Flag similarity field. Negligible differences should be listed only when relevant, notably when two flags share nothing but negligible differences.

Map field

This field must contain a single HTML image element pointing to the PNG image of a map - e.g. <img src="ug-map-seychelles.png" />. The image must be placed in the media folder and named ug-map-<country_name>.png. PNG is the preferred format.

The source SVG maps come, or are inspired, from the SVG locator maps project on Wikimedia. The maps' source URLs and licences must be documented in sources.csv.

The following guidelines apply to map images:

The maps must be sourced or created as SVG, exported to PNG, and then optimised with a tool like PNGGauntlet.
They should have a width of 500 px and a height of approximately 281 px.
The style (colours, strokes, etc.) should match that of existing maps in the deck (note that water bodies use a different style than countries).
For small islands or archipelagos, the map should include a zoom box to facilitate identification.

Writing style

As mentioned above, we strive to keep the descriptive fields (Capital info, Capital hint, Country info, Flag similarity) as concise as possible. For instance, where the subject of the description is the same as the subject of the card, we use a truncated phrase instead of a full sentence — e.g. "Also known as Kiev.", rather than "Kyiv is also known as Kiev.".

By convention and for consistency, we use a full stop at the end of the Capital info and Country info fields and no full stop for the Capital hint and Flag similarity fields, in all languages, unless there are strong typographic or grammatical reasons against this in the given language. (No such language is currently in the deck.) The justification for this convention is described in #383.

Translation sources

When Wikipedia in a given language is not sufficiently exhaustive to support the translation of this deck, additional sources may be used. This section references such sources, as well as any stylistic choices made by translators.

Norwegian Bokmål

Norwegian Bokmål (nb-NO) is the preferred written-language standard of roughly 90% of Norway's population, with the remaining 10% preferring Norwegian Nynorsk (nn-NO). With regard to style and grammar, we have chosen a conservative style (riksmål), preferring feminine-gendered nouns only in the case of bays and islands ("-bukta" and "-øya", e.g. Biscayabukta instead of Biscayabukten).

The Norwegian Bokmål translation is based on the following sources (in addition to the English deck), listed in order of priority:

Store norske leksikon (The Large Norwegian Encyclopedia) - Open to audience contributions, edited by professionals. The editors are usually academics. In the original translator's opinion a good trade-off between being quickly updated and being correct.
Country names, capitals, and national holidays - This brochure from the Norwegian Ministry of Foreign Affairs is the most authoritative source for country names in Norwegian, as it is used by Norwegian diplomats. There are a few weaknesses:
- The brochure is not updated often, possibly due to a lack of attention or diplomatic reasons for lagging behind de facto changes.
- Only includes sovereign countries.
Wikipedia in Norwegian (Bokmål) - Used when neither of the above sources were enough to verify spelling.

Portuguese

Portuguese is used in several countries around the world, with some significant differences between the dialects from different countries. The two principal sets of dialects are European Portuguese (pt-PT) and Brazilian Portuguese (pt-BR). We have decided to use Brazilian Portuguese in the Capital hint, Capital info, Country info and Flag similarity fields.

In cases where the Wikipedia article about the given country or city provides two spellings, describing them as the Brazilian Portuguese and European Portuguese versions (e.g. Romênia (português brasileiro) ou Roménia (português europeu)), we provide both in the given Country or City field, with (BR) and (PT) in parentheses to indicate the dialects (e.g. "Romênia (BR), Roménia (PT)"). This explicitly overrides the recommendation in the Country field content guidelines regarding using the title of the Wikipedia article.

As suggested above, the country or city names used in the other fields should be the Brazilian spellings.

Danish

The Danish translation is based on the following sources (in addition to the English deck), listed in order of priority:

Lande og nationaliteter - This list is maintained by the "Danske Sprognævn".
Den Store Danske - Denmarks national encyclopedia.
Wikipedia in Danish - Used when neither of the above sources where enough to verify spelling.

Maintainer's guide

Versioning

The releases follow a versioning scheme of the form x.y, where:

x increases in the case of a major, breaking release (e.g. v3.0),
y increases in the case of a minor, non-breaking release (e.g. v2.6).

Content changes, such as adding a note, replacing an image, or translating the deck into a new language, all constitute minor changes. A change is considered major when users are likely to lose a significant part of their progress when upgrading the deck with CrowdAnki.

Release process

Open a discussion thread named Prepare for v[x.y] a few weeks ahead of the release to coordinate any remaining work.
When ready to release, bump the version number in src/headers/desc.html.
Run pipenv run build.
In Anki, synchronise all your devices then upgrade the standard English deck by following the recommended procedure, which was agreed upon in the discussion thread. Synchronise all your devices again once the upgrade is complete.
With the help of the Anki card browser, update the notes/cards stats in both desc.html and README.md, and commit the changes (including the version bump).
Run pipenv run build again.
Reimport the standard English deck in Anki and synchronise with AnkiWeb.
Add each folder in the build directory to a separate ZIP archive named as follows:
- Ultimate Geography [EN] ==> Ultimate_Geography_v[x.y]_EN.zip.
- Ultimate Geography [EN] [Extended] ==> Ultimate_Geography_v[x.y]_EN_EXTENDED.zip.
On GitHub, create a new release named after the version number.
Draft the release notes, making sure to add a link to the upgrade steps in the README and/or in the wiki.
Attach all the ZIP files and save the draft release notes.
Post a link to the draft release notes on the Prepare for v[x.y] discussion thread and wait for feedback.
Once maintainers have reviewed the release notes and the upgrade process, open the draft release notes, and publish the release.
Open a discussion thread to announce the release, with links to the release notes and upgrade instructions.
Close the milestone and create a new one for the next minor version.
Go to AnkiWeb.
Find the Ultimate Geography deck and select Actions > Share
Update the version number in the title and, if needed, update the description with the content of desc.html.
Tick the Copyright box and click Share.
Announce the release on Reddit, with links to the release notes, to the upgrade instructions, and to the Discussions and Issues pages.

Files

CONTRIBUTING.md

Latest commit

History