Merge pull request #242 from Amulet-Team/impl-contributing

Improved Contributing

.github/workflows/python-stylecheck.yml

@@ -28,5 +28,4 @@ jobs:
         pip install black
     - name: run stylecheck
       run: |
-        python -m black --check --diff amulet_map_editor
-        python -m black --check --diff tests
+        python -m black --check --diff .

contributing.md

@@ -1,29 +1,8 @@
 ## Contributing
 
-### Branch Naming
-Branches should be created when a certain bug or feature may take multiple attempts to fix. Naming
-them should follow the following convention (even for forked repositories when a pull request is being made):
+If you wish to report a bug in the program or suggest a feature please first [search the existing bugs and features](https://github.com/Amulet-Team/Amulet-Map-Editor/issues) to see if it already exists.
+If not [create a new issue](https://github.com/Amulet-Team/Amulet-Map-Editor/issues/new/choose).
 
-* For features, use: `impl-<feature name>`
-* For bug fixes, use: `bug-<bug tracker ID>`
-* For improvements/rewrites, use: `improv-<feature name>`
-* For prototyping, use: `proto-<feature name>`
+If you wish to contribute translations to the project see [the translation guidelines](contributing/lang.md)
 
-### Code Formatting
-For code formatting, we use the formatting utility [black](https://github.com/ambv/black). To run
-it on a file, run the following command from your favorite terminal after installing: `black <path to file>`
-
-While formatting is not strictly required for each commit, we ask that after you've finished your
-code changes for your Pull Request to run it on every changed file.
-
-### Pull Requests
-We ask that submitted Pull Requests give moderately detailed notes about the changes and explain 
-any changes that were made to the program outside of those directly related to the feature/bug-fix.
-Please make sure to run all tests and include a written verification that all tests have passed.
-
-_Note: We will also re-run all tests before reviewing, this is to mitigate additional changes/commits
-needed to pass all tests._
-
-Once a Pull Request is submitted, we will mark the request for review, once that is done, we will
-review the changes and provide any notes/things to change. Once all additional changes have been made,
-we will merge the request.
+If you wish to contribute code to the project see [the developer guidelines](contributing/dev.md)

contributing/dev.md

@@ -0,0 +1,38 @@
+## Developer Contributing
+
+This is intended for developers wishing to contribute code to the project.
+
+### Branch Naming
+A branch must be created in order to contribute code to the project.
+Unless you have permissions to create branches in Amulet-Team you will first need to [fork the repository](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).
+You must then create a branch with an identifiable name using the following convention:
+
+* For features, use: `impl-<feature name>`
+* For bug fixes, use: `bug-<bug tracker ID>`
+* For improvements/rewrites, use: `improv-<feature name>`
+* For prototyping, use: `proto-<feature name>`
+
+### Tests
+There are a number of tests to make sure that the code behaves correctly.
+If you are making changes to the code these should be run before creating the pull request.
+
+### Code Formatting
+For code formatting, we use the formatting utility [black](https://github.com/ambv/black).
+To run it on a file, run the following command from your favorite terminal after installing: `black <path to file>`
+
+While formatting is not strictly required for each commit, we ask that after you've finished your
+code changes for your Pull Request to run it on every changed file.
+
+The following command will run it on all files. `black .`
+
+### Pull Requests
+Once you have added the desired changes and run tests and formatting you will need to [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). 
+We ask that submitted Pull Requests give moderately detailed notes about the changes and explain 
+any changes that were made to the program outside of those directly related to the feature/bug-fix.
+
+Once a Pull Request is submitted, we will mark the request for review.
+Once that is done, we will review the changes and may provide feedback on things to change.
+Once all additional changes have been made, we will merge the request.
+
+The tests and code formatting will be run automatically when the pull request is created to verify that everything is okay.
+This can be seen at the bottom of the pull request page.

contributing/lang.md

@@ -0,0 +1,31 @@
+## Language Contributing
+
+This is intended for anyone wishing to contribute translations to the project.
+
+### Language Files
+In order to support translations of text in the user interface all of the text has been moved into .lang files located in `amulet_map_editor/lang`.
+The name of these lang files are RFC 1766 format language codes.
+For example `en` for English, `en_US` for US English and `en_GB` for British English.
+The lang files are formatted with one localised string per line with a `=` symbol separating the identifying key and the localised text.
+The keys must only contain the characters a-z0-9_. and values can contain any character including the `=` symbol.
+
+When loading the lang files, first the `en.lang` file is loaded to ensure that there is at least something for any given key.
+If the language code contains an `_` symbol (for example `fr_CA`) then the lang file for the language section will be loaded next (`fr.lang`).
+This allows languages that do not vary much between regions to share the same language file to minimise duplication.
+Finally, if it exists, the region specific language file will be loaded which should only contain entries that vary between regions. 
+
+### Branch Naming
+A branch must be created in order to contribute to the project.
+Unless you have permissions to create branches in Amulet-Team you will first need to [fork the repository](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).
+You must then create a branch with an identifiable name using the following convention:
+
+* When adding languages, use: `impl-lang-<langauge code>`
+* When fixing languages, use: `improv-lang-<langauge code>`
+
+### Pull Requests
+Once you have added the desired changes you will need to [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). 
+We ask that submitted Pull Requests give moderately detailed notes about the changes.
+
+Once a Pull Request is submitted, we will mark the request for review.
+Once that is done, we will review the changes and may provide feedback on things to change.
+Once all additional changes have been made, we will merge the request.

setup.py

@@ -27,25 +27,12 @@ def load_requirements(path: str) -> List[str]:
 required_packages = load_requirements("./requirements.txt")
 
 package_data = [
-    os.path.relpath(path, "amulet_map_editor") for path in
-    set(
-        glob.glob(
-            os.path.join(
-                "amulet_map_editor",
-                "**",
-                "*.*"
-            ),
-            recursive=True
-        )
-    ) - set(
-        glob.glob(
-            os.path.join(
-                "amulet_map_editor",
-                "**",
-                "*.py[cod]"
-            ),
-            recursive=True
-        )
+    os.path.relpath(path, "amulet_map_editor")
+    for path in set(
+        glob.glob(os.path.join("amulet_map_editor", "**", "*.*"), recursive=True)
+    )
+    - set(
+        glob.glob(os.path.join("amulet_map_editor", "**", "*.py[cod]"), recursive=True)
     )
 ]
 
@@ -70,5 +57,5 @@ def load_requirements(path: str) -> List[str]:
         "Programming Language :: Python :: 3",
         "Operating System :: OS Independent",
     ],
-    python_requires='>=3.6',
+    python_requires=">=3.6",
 )

tests/test_lang.py

@@ -0,0 +1,52 @@
+import os
+import glob
+import string
+import unittest
+import amulet_map_editor
+
+KeyCharacterSet = set(string.ascii_lowercase + string.digits + "_.")
+
+
+class LangTestCase(unittest.TestCase):
+    def test_lang(self):
+        for lang_path in glob.glob(
+            os.path.join(amulet_map_editor.__path__[0], "lang", "*")
+        ):
+            self.assertTrue(
+                lang_path.endswith(".lang"), f'{lang_path} does not end with ".lang".'
+            )
+            self.assertTrue(os.path.isfile(lang_path), f"{lang_path} is not a file.")
+            with open(lang_path, encoding="utf-8") as f:
+                unique_ids = set()
+                for line_number, line in enumerate(f.readlines()):
+                    line_number += 1
+                    if line.strip() and not line.startswith("#"):
+                        split_line = line.split("=", 1)
+                        self.assertEqual(
+                            len(split_line),
+                            2,
+                            f"{lang_path} line {line_number}: No = symbol present.",
+                        )
+                        unique_identifier = split_line[0].strip()
+                        self.assertTrue(
+                            len(unique_identifier) > 0,
+                            f"{lang_path} line {line_number}: There is no identifier before the first = symbol.",
+                        )
+                        self.assertTrue(
+                            set(unique_identifier).issubset(KeyCharacterSet),
+                            f"{lang_path} line {line_number}: identifier is not a subset of a-z0-9_.",
+                        )
+                        self.assertTrue(
+                            unique_identifier not in unique_ids,
+                            f"{lang_path} line {line_number}: identifier already defined in the file.",
+                        )
+                        unique_ids.add(unique_identifier)
+                        language_string = split_line[1].replace("\\n", "\n").strip()
+                        self.assertTrue(
+                            len(language_string) > 0,
+                            f"{lang_path} line {line_number}: There is no translation string after the first = symbol.",
+                        )
+
+
+if __name__ == "__main__":
+    unittest.main()