From 3edf4ed069858d047d2873ecf1728c963a225b49 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 7 Jun 2021 12:04:14 +0100 Subject: [PATCH 01/13] Contributing: re-format 'Work on Issues' --- Contributing.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 4dc629ec..0dd7c1d6 100644 --- a/Contributing.md +++ b/Contributing.md @@ -7,7 +7,10 @@ vim: textwidth=79 wrapmargin=79 If you are not part of the core development team then you should only be performing work that addresses an open issue. -So, if what you think needs doing isn't currently referred to in an [open issue](https://github.com/EDCD/EDMarketConnector/issues), then you should first [open an issue](https://github.com/EDCD/EDMarketConnector/issues/new/choose) **please use the correct template if applicable**. +So, if what you think needs doing isn't currently referred to in an +[open issue](https://github.com/EDCD/EDMarketConnector/issues), +then you should first [open an issue](https://github.com/EDCD/EDMarketConnector/issues/new/choose). +**Please use the correct template if applicable**. ## Check with us first From 54b57db329713289e8d4a1f3d0e853ee76b29f9b Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 7 Jun 2021 12:10:43 +0100 Subject: [PATCH 02/13] Contributing: // now mandated --- Contributing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Contributing.md b/Contributing.md index 0dd7c1d6..f71d5673 100644 --- a/Contributing.md +++ b/Contributing.md @@ -129,12 +129,12 @@ Remember, you should always be working versus a single issue, even if the work i There might be cases where issues aren't duplicates, but your work still addresses more than one. In that case pick one for the naming scheme below, but mention all in commit messages and the Pull Request. -In all cases the branch should be named as per the scheme `<class>/<issue number>-<title>`: +In all cases the branch should be named as per the scheme `<class>/<issue number>/<title>`: * `<class>` - We have several classes of WIP branch: - * `fix` - For working on bug fixes, e.g. `fix/184-crash-in-startup` - * `enhancement` - For enhancing an *existing* feature, e.g. `enhancement/192-add-thing-to-wotsit` - * `feature` - For working on *new* features, e.g. `feature/284-allow-users-to-frob` + * `fix` - For working on bug fixes, e.g. `fix/184/crash-in-startup` + * `enhancement` - For enhancing an *existing* feature, e.g. `enhancement/192/add-thing-to-wotsit` + * `feature` - For working on *new* features, e.g. `feature/284/allow-users-to-frob` * `<issue-number>` is for easy reference when citing the issue number in commit messages. If you're somehow doing work that's not versus an issue then don't put the `<issue number>-` part in. From 9dcb79a5dbdea0e83304e2aedaeae3e4dc161dd1 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:11:58 +0100 Subject: [PATCH 03/13] Contributing: Minor grammar/punctuation --- Contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contributing.md b/Contributing.md index f71d5673..b4547233 100644 --- a/Contributing.md +++ b/Contributing.md @@ -142,13 +142,13 @@ In all cases the branch should be named as per the scheme `<class>/<issue number succinct for `<title>`, it's just there for easy reference, it doesn't need to be the entire title of the appropriate issue. -Which branch you base your work on will depend on which class of WIP it is. If you're fixing a bug in the latest +The branch you base your work on will depend on which class of WIP it is. If you're fixing a bug in the latest `stable` then it's best to base your branch on its HEAD. If it's a fix for a beta release then base off of `beta`'s HEAD. If you're working on a new feature then you'd want to base the work on `develop`'s HEAD. **Important**: Please *under no circumstance* merge *from* the source branch after you have started work in your WIP branch. If there are any non-trivial conflicts when we merge your Pull Request then we might ask you -to rebase your WIP branch on the latest version of the source branch. Otherwise we'll work out how to best +to *rebase* your WIP branch on the latest version of the source branch. Otherwise, we'll work out how to best merge your changes via comments in the Pull Request. ## Linting From 3c13e84910599f4a4df4704b2727efdeb797f752 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:18:56 +0100 Subject: [PATCH 04/13] Contributing: Re-arrange sections more logically 1. General workflow first. 2. Then branches, including 'work in progress'. 3. Followed by tags. 4. *Then* 'Version conventions'. --- Contributing.md | 136 ++++++++++++++++++++++++------------------------ 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/Contributing.md b/Contributing.md index b4547233..add45dbb 100644 --- a/Contributing.md +++ b/Contributing.md @@ -23,22 +23,25 @@ consistent with our vision for EDMC. Fundamental changes in particular need to b --- -## Version conventions +## General workflow -Please see [Version Strings](docs/Releasing.md#version-strings) -for a description of the currently used version strings. +1. You will need a GitHub account. +1. Fork the repository on GitHub into your account there (hereafter referred to as 'your fork'). +1. In your local copy of *your* fork create an appropriate WIP branch. +1. Develop the changes, testing as you go (no we don't have any actual tests yet). + 1. Be as sure as you can that the code works as you intend and hasn't introduced any other bugs or regressions. + 1. Test the codebase as a whole against any unit tests that do exist, and add your own as you can. + 1. Check your code against flake8 periodically. +1. When you're sure the work is final: + 1. Push your WIP branch to your fork (you probably should have been doing this as you worked as a form of backup). + 1. Access the WIP branch on your fork on GitHub and create a Pull Request. Mention any Issue number(s) that it + addresses. +1. Await feedback in the form of comments on the Pull Request. -Historically a `A.BC` form was used, based on an internal `A.B.C.D` version -string. This was changed to simply `A.B.C.D` throughout for `4.0.0.0`, -`4.0.1.0` and `4.0.2.0`. It would also continue for any other increment of -only the 'C' (Patch) component. - -Going forwards we will always use the full [Semantic Version](https://semver.org/#semantic-versioning-specification-semver) -and 'folder style' tag names, e.g. `Release/Major.Minor.Patch`. - -Currently the only file that defines the version code-wise is `config.py`. -`Changelog.md` and `edmarketconnector.xml` are another matter handled as part -of [the release process](docs/Releasing.md#distribution). +**IMPORTANT**: Once you have created the Pull Request *any changes you make to that WIP branch and push to your fork +will be reflected in the Pull Request*. Ensure that *only* the changes for the issue(s) you are addressing are in +the WIP branch. Any other work should occur in its own separate WIP branch. If needs be make one branch to work in +and another for the Pull Request, merging or cherry-picking commits as needed. --- @@ -46,15 +49,15 @@ of [the release process](docs/Releasing.md#distribution). Somewhat based on git-flow, but our particular take on it: -## Branches +### Branches -### `stable` +#### `stable` This will either have `HEAD` pointing to the latest stable release code *or* might have extra code merged in for a hotfix that will shortly be in the next stable release. If you want the latest stable release code then use the appropriate `Release/A.B.C` tag! -### `beta` +#### `beta` If we run any pre-release betas *with actual builds released, not just a branch to be run from source*, then this branch will contain that @@ -64,13 +67,13 @@ to be sure of the code you checkout. *If there hasn't yet been a new beta version this could be far behind all of: `main`, `develop`, `stable`.* -### `develop` +#### `develop` This is the branch where all current development is integrated. No commits should be made directly to this as the work should be done in a separate branch used in a Pull Request before being merged as part of resolving that Pull Request. -### `main` +#### `main` Yes, we've renamed this from `master`. See "[Using 'main' as the primary branch in Git](https://github.com/EDCD/EDMarketConnector/wiki/Git-Using-Main-Branch)" @@ -79,11 +82,11 @@ for instructions on ensuring you're cleanly using it in any local clone. This branch should contain anything from `develop` that is considered well tested and ready for the next `stable` merge. -### `master` +#### `master` **This is no longer used. If the branch is even present then it's no longer updated. You should be using `main` instead.** -### `releases` +#### `releases` Currently the version of the `edmarketconnector.xml` 'appcast' file in this branch is what live clients check to be notified of new versions. This can potentially be replaced with the `stable` branch's version, @@ -91,14 +94,42 @@ but some care will be necessary to ensure no users are left behind (their client then no longer exists). For the time being this should always be kept in sync with `stable` as each new release is made. -## Tags +### Work in progress conventions -### Stable Releases +Remember, you should always be working versus a single issue, even if the work is part of a Milestone or Project. +There might be cases where issues aren't duplicates, but your work still addresses more than one. In that case +pick one for the naming scheme below, but mention all in commit messages and the Pull Request. + +In all cases the branch should be named as per the scheme `<class>/<issue number>/<title>`: + +* `<class>` - We have several classes of WIP branch: + * `fix` - For working on bug fixes, e.g. `fix/184/crash-in-startup` + * `enhancement` - For enhancing an *existing* feature, e.g. `enhancement/192/add-thing-to-wotsit` + * `feature` - For working on *new* features, e.g. `feature/284/allow-users-to-frob` + +* `<issue-number>` is for easy reference when citing the issue number in commit messages. If you're somehow doing + work that's not versus an issue then don't put the `<issue number>-` part in. +* `<title>` is intended to allow anyone to quickly know what the branch is addressing. Try to choose something + succinct for `<title>`, it's just there for easy reference, it doesn't need to be the entire title of + the appropriate issue. + +The branch you base your work on will depend on which class of WIP it is. If you're fixing a bug in the latest +`stable` then it's best to base your branch on its HEAD. If it's a fix for a beta release then base off of `beta`'s +HEAD. If you're working on a new feature then you'd want to base the work on `develop`'s HEAD. + +**Important**: Please *under no circumstance* merge *from* the source branch after you have started work in +your WIP branch. If there are any non-trivial conflicts when we merge your Pull Request then we might ask you +to *rebase* your WIP branch on the latest version of the source branch. Otherwise, we'll work out how to best +merge your changes via comments in the Pull Request. + +### Tags + +#### Stable Releases All stable releases **MUST** have a tag of the form `Release/Major.Minor.Patch` on the commit that was `HEAD` when the installer for it was built. -### Pre-Releases +#### Pre-Releases Tags for pre-releases should be of one of two forms, following [Version Strings](docs/Releasing.md#version-strings) conventions. @@ -123,33 +154,24 @@ The Semantic Versioning `+<build metadata>` should never be a part of the tag. --- -## Work in progress conventions +## Version conventions -Remember, you should always be working versus a single issue, even if the work is part of a Milestone or Project. -There might be cases where issues aren't duplicates, but your work still addresses more than one. In that case -pick one for the naming scheme below, but mention all in commit messages and the Pull Request. +Please see [Version Strings](docs/Releasing.md#version-strings) +for a description of the currently used version strings. -In all cases the branch should be named as per the scheme `<class>/<issue number>/<title>`: +Historically a `A.BC` form was used, based on an internal `A.B.C.D` version +string. This was changed to simply `A.B.C.D` throughout for `4.0.0.0`, +`4.0.1.0` and `4.0.2.0`. It would also continue for any other increment of +only the 'C' (Patch) component. -* `<class>` - We have several classes of WIP branch: - * `fix` - For working on bug fixes, e.g. `fix/184/crash-in-startup` - * `enhancement` - For enhancing an *existing* feature, e.g. `enhancement/192/add-thing-to-wotsit` - * `feature` - For working on *new* features, e.g. `feature/284/allow-users-to-frob` +Going forwards we will always use the full [Semantic Version](https://semver.org/#semantic-versioning-specification-semver) +and 'folder style' tag names, e.g. `Release/Major.Minor.Patch`. -* `<issue-number>` is for easy reference when citing the issue number in commit messages. If you're somehow doing - work that's not versus an issue then don't put the `<issue number>-` part in. -* `<title>` is intended to allow anyone to quickly know what the branch is addressing. Try to choose something - succinct for `<title>`, it's just there for easy reference, it doesn't need to be the entire title of - the appropriate issue. +Currently the only file that defines the version code-wise is `config.py`. +`Changelog.md` and `edmarketconnector.xml` are another matter handled as part +of [the release process](docs/Releasing.md#distribution). -The branch you base your work on will depend on which class of WIP it is. If you're fixing a bug in the latest -`stable` then it's best to base your branch on its HEAD. If it's a fix for a beta release then base off of `beta`'s -HEAD. If you're working on a new feature then you'd want to base the work on `develop`'s HEAD. - -**Important**: Please *under no circumstance* merge *from* the source branch after you have started work in -your WIP branch. If there are any non-trivial conflicts when we merge your Pull Request then we might ask you -to *rebase* your WIP branch on the latest version of the source branch. Otherwise, we'll work out how to best -merge your changes via comments in the Pull Request. +--- ## Linting @@ -193,28 +215,6 @@ Otherwise, see the [pytest documentation](https://docs.pytest.org/en/stable/cont --- -## General workflow - -1. You will need a GitHub account. -1. Fork the repository on GitHub into your account there (hereafter referred to as 'your fork'). -1. In your local copy of *your* fork create an appropriate WIP branch. -1. Develop the changes, testing as you go (no we don't have any actual tests yet). - 1. Be as sure as you can that the code works as you intend and hasn't introduced any other bugs or regressions. - 1. Test the codebase as a whole against any unit tests that do exist, and add your own as you can. - 1. Check your code against flake8 periodically. -1. When you're sure the work is final: - 1. Push your WIP branch to your fork (you probably should have been doing this as you worked as a form of backup). - 1. Access the WIP branch on your fork on GitHub and create a Pull Request. Mention any Issue number(s) that it - addresses. -1. Await feedback in the form of comments on the Pull Request. - -**IMPORTANT**: Once you have created the Pull Request *any changes you make to that WIP branch and push to your fork -will be reflected in the Pull Request*. Ensure that *only* the changes for the issue(s) you are addressing are in -the WIP branch. Any other work should occur in its own separate WIP branch. If needs be make one branch to work in -and another for the Pull Request, merging or cherry-picking commits as needed. - ---- - ## Coding Conventions ### In general, please follow [PEP8](https://www.python.org/dev/peps/pep-0008/) From 81652a54c2dc13c35546c9d11d353ccdfa019a21 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:21:00 +0100 Subject: [PATCH 05/13] Contributing: --- separators between each ## --- Contributing.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Contributing.md b/Contributing.md index add45dbb..ee1573bf 100644 --- a/Contributing.md +++ b/Contributing.md @@ -223,6 +223,8 @@ Otherwise, see the [pytest documentation](https://docs.pytest.org/en/stable/cont Yes, this means using 'color' rather than 'colour', and in general will mean US, not British, spellings. +--- + ## Control flow Never oneline any control flow (`if`, `else`, `for`), as it makes spotting what happens next difficult. @@ -268,11 +270,15 @@ No: return ``` +--- + ## Use Type hints Please do place [type hints](https://docs.python.org/3/library/typing.html) on the declarations of your functions, both their arguments and return types. +--- + ## Use `logging` not `print()`, and definitely not `sys.stdout.write()` `EDMarketConnector.py` sets up a `logging.Logger` for this under the @@ -352,6 +358,8 @@ In addition to that we utilise one of the user-defined levels as: command-line argument and `.bat` file for users to enable it. It cannot be selected from Settings in the UI. +--- + ## Prefer fstrings to modulo-formatting and .format [fstrings](https://www.python.org/dev/peps/pep-0498/) are new in python 3.6, and allow for string interpolation rather @@ -360,11 +368,15 @@ than more opaque formatting calls. As part of our flake8 linting setup we have included a linter that warns when you use either `%` or `.format` on string literals. +--- + ## Docstrings Doc strings are preferred on all new modules, functions, classes, and methods, as they help others understand your code. We use the `sphinx` formatting style, which for pycharm users is the default. +--- + ## Comments ### Add comments to LANG usage From 93dbaee5ae5ac6b90f9c8169482fae7991023f6f Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:26:01 +0100 Subject: [PATCH 06/13] Contributing: "Git commit conventions" after "General workflow" Also linkified to the GitHub docs about 'Closes #XXX' and the like. --- Contributing.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/Contributing.md b/Contributing.md index ee1573bf..19da9e15 100644 --- a/Contributing.md +++ b/Contributing.md @@ -45,6 +45,20 @@ and another for the Pull Request, merging or cherry-picking commits as needed. --- +## Git commit conventions + +* Please use the standard Git convention of a short title in the first line and fuller body text in subsequent lines. +* Please reference issue numbers using the "hashtag" format #123 in your commit message wherever possible. + This lets GitHub create two-way hyperlinks between the issue report and the commit. + [Certain text](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) + in a PR that fixes an issue can auto-close the issue when the PR is merged. + Note the caveats about the extended forms being necessary in some situations. +* If in doubt, lean towards many small commits. This makes git bisect much more useful. +* Please try at all costs to avoid a "mixed-up" commit, i.e. one that addresses more than one issue at once. + One thing at a time is best. + +--- + ## Git branch structure and tag conventions Somewhat based on git-flow, but our particular take on it: @@ -409,18 +423,6 @@ Additionally, if your hack is over around 5 lines, please include a `# HACK END` --- -## Git commit conventions - -* Please use the standard Git convention of a short title in the first line and fuller body text in subsequent lines. -* Please reference issue numbers using the "hashtag" format #123 in your commit message wherever possible. - This lets GitHub create two-way hyperlinks between the issue report and the commit. - Certain text in a PR that fixes an issue can auto-close the issue when the PR is merged. -* If in doubt, lean towards many small commits. This makes git bisect much more useful. -* Please try at all costs to avoid a "mixed-up" commit, i.e. one that addresses more than one issue at once. - One thing at a time is best. - ---- - ## Build process See [Releasing.md](docs/Releasing.md) for the environment and procedure necessary for building the application into From 522f15b0c6f77d7dc3c66df4a774df4d2965f8e9 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:27:45 +0100 Subject: [PATCH 07/13] Contributing: 'Coding Conventions' content shouldn't be headers --- Contributing.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Contributing.md b/Contributing.md index 19da9e15..79ccc8b8 100644 --- a/Contributing.md +++ b/Contributing.md @@ -231,11 +231,13 @@ Otherwise, see the [pytest documentation](https://docs.pytest.org/en/stable/cont ## Coding Conventions -### In general, please follow [PEP8](https://www.python.org/dev/peps/pep-0008/) +In general, please follow [PEP8](https://www.python.org/dev/peps/pep-0008/) -### Adhere to the spelling conventions of the libraries and modules used in the project +Adhere to the spelling conventions of the libraries and modules used in the +project. -Yes, this means using 'color' rather than 'colour', and in general will mean US, not British, spellings. +Yes, this means using 'color' rather than 'colour', and in general will mean +US, not British, spellings. --- From e548dce4d84823014a1f9016cc060568d7e6f10c Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:31:05 +0100 Subject: [PATCH 08/13] Contributing: Reference Plugin logging documentation --- Contributing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Contributing.md b/Contributing.md index 79ccc8b8..07fd7fae 100644 --- a/Contributing.md +++ b/Contributing.md @@ -319,6 +319,8 @@ except Exception as e: # Try to be more specific from EDMarketConnector import logger ``` +Setting up [logging in plugins](./PLUGINS.md#logging) is slightly different. + We have implemented a `logging.Filter` that adds support for the following in `logging.Formatter()` strings: From f7272ee445cf9b6028dc40d77a008aa8478a5b00 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:32:12 +0100 Subject: [PATCH 09/13] Contributing: fstrings are mandatory, not only preferred Legacy code aside.... --- Contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 07fd7fae..46f39d77 100644 --- a/Contributing.md +++ b/Contributing.md @@ -378,7 +378,7 @@ In addition to that we utilise one of the user-defined levels as: --- -## Prefer fstrings to modulo-formatting and .format +## Use fstrings, not modulo-formatting or .format [fstrings](https://www.python.org/dev/peps/pep-0498/) are new in python 3.6, and allow for string interpolation rather than more opaque formatting calls. From da790826e99571c20399028d8c6866e54b4d8273 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:33:12 +0100 Subject: [PATCH 10/13] Contributing: missing/incorrect docstrings will fail flake8 --- Contributing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Contributing.md b/Contributing.md index 46f39d77..3cd30877 100644 --- a/Contributing.md +++ b/Contributing.md @@ -393,6 +393,9 @@ literals. Doc strings are preferred on all new modules, functions, classes, and methods, as they help others understand your code. We use the `sphinx` formatting style, which for pycharm users is the default. +Lack of docstrings, or them not passing some checks, *will* cause a flake8 +failure in our setup. + --- ## Comments From 5c8b5b99148114740a9910c8e403a9627db302d0 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:39:18 +0100 Subject: [PATCH 11/13] Translations: Correct example of a non-translated {WORD} The code needs to perform the replacement *after* translation phrase look up. --- docs/Translations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Translations.md b/docs/Translations.md index 89e3f850..ce26c588 100644 --- a/docs/Translations.md +++ b/docs/Translations.md @@ -13,7 +13,7 @@ If you add any new strings that appear in the application UI, e.g. new configura If you need to specify something in the text that shouldn't be translated then use the form: - _('Some text with a {WORD} not translated'.format(WORD='word')) + _('Some text with a {WORD} not translated').format(WORD='word') This way 'word' will always be used literally. Next you will need to edit `L10n/en.template` to add the phrase: From d304c3260277535bf626a56041b51cbc581ba732 Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:47:48 +0100 Subject: [PATCH 12/13] Translations: LANG comment in here, not Contributing Also changed to `# header` style formatting, with `---` separators between major sections. --- Contributing.md | 13 +++---------- docs/Translations.md | 44 ++++++++++++++++++++++++++++++++------------ 2 files changed, 35 insertions(+), 22 deletions(-) diff --git a/Contributing.md b/Contributing.md index 3cd30877..3009a086 100644 --- a/Contributing.md +++ b/Contributing.md @@ -400,17 +400,10 @@ failure in our setup. ## Comments -### Add comments to LANG usage +### LANG comments for translations -Sometimes our translators may need some additional information about what a translation is used for. You can add -that information automatically by using `# LANG: your message here` -**on the line directly above your usage, or at the end of the line in your usage**. If both comments exist, the one -on the current line is preferred over the one above - -```py -# LANG: this says stuff. -_('stuff') -``` +When adding translations you *must* +[add a LANG comment](./docs/Translations.md#add-a-lang-comment). ### Mark hacks and workarounds with a specific comment diff --git a/docs/Translations.md b/docs/Translations.md index ce26c588..6516269d 100644 --- a/docs/Translations.md +++ b/docs/Translations.md @@ -1,11 +1,14 @@ -Introduction -=== +# Translations in Elite Dangerous Market Connector + Translations are handled on [OneSky](https://oneskyapp.com/), specifically in [this project](https://marginal.oneskyapp.com/collaboration/project/52710). -Adding A New Phrase -=== -Setting it up in the code --- + +## Adding A New Phrase + +### Setting it up in the code + +#### Call `_(...)` If you add any new strings that appear in the application UI, e.g. new configuration options, then you should specify them as: _('Text that appears in UI') @@ -16,7 +19,20 @@ If you need to specify something in the text that shouldn't be translated then u _('Some text with a {WORD} not translated').format(WORD='word') This way 'word' will always be used literally. -Next you will need to edit `L10n/en.template` to add the phrase: +#### Add a LANG comment + +Sometimes our translators may need some additional information about what a +translation is used for. You can add that information automatically by using +`# LANG: your message here` **on the line directly above your usage, or at the +end of the line in your usage**. If both comments exist, the one on the +current line is preferred over the one above + +```py +# LANG: this says stuff. +_('stuff') +``` + +#### Edit `L10n/en.template` to add the phrase /* <use of this phrase> [<file it was first added in>] */ "<text as it appears in the code>" = "<English version of the text>"; @@ -43,8 +59,8 @@ You can even use other translations within a given string, e.g.: /* Popup body: Warning about plugins without Python 3.x support [EDMarketConnector.py] */ "One or more of your enabled plugins do not yet have support for Python 3.x. Please see the list on the '{PLUGINS}' tab of '{FILE}' > '{SETTINGS}'. You should check if there is an updated version available, else alert the developer that they need to update the code for Python 3.x.\r\n\r\nYou can disable a plugin by renaming its folder to have '{DISABLED}' on the end of the name." = "One or more of your enabled plugins do not yet have support for Python 3.x. Please see the list on the '{PLUGINS}' tab of '{FILE}' > '{SETTINGS}'. You should check if there is an updated version available, else alert the developer that they need to update the code for Python 3.x.\r\n\r\nYou can disable a plugin by renaming its folder to have '{DISABLED}' on the end of the name."; -Adding it to the OneSky project ---- +## Adding it to the OneSky project + You will, of course, need admin access to the project. Jonathan Harris (aka Maringal, aka Otis) still handles this. Check for this email address in github commits if you need to get in touch. 1. Copy `L10n/en.template` to `en.strings` somewhere. It needs to be this name for OneSky to accept it as an upload. @@ -56,8 +72,10 @@ You will, of course, need admin access to the project. Jonathan Harris (aka Mar All project admins will get a notification of the new upload. Now you wait for translators to work on the new/changed phrases. -Updating Translations In The Code -=== +--- + +## Updating Translations In The Code + Once you have new/changed translations on OneSky you'll want to update the code to use them. 1. Navigate to the [Translation Overview](https://marginal.oneskyapp.com/admin/project/dashboard/project/52710) then click on "Download Translation" which should bring you to [Download](https://marginal.oneskyapp.com/admin/export/phrases/project/52710). @@ -69,8 +87,10 @@ Once you have new/changed translations on OneSky you'll want to update the code 1. Rename the "en.strings" file to "en.template". 1. Commit the changes to git. -Adding a New Language -=== +--- + +## Adding a New Language + To add a new language to the app: 1. Add it to the OneSkyApp project: From 9d46b6a7b06d09adca6c7136a46abd67554e7e4a Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Mon, 7 Jun 2021 12:58:45 +0100 Subject: [PATCH 13/13] Contributing: .format() still acceptable wrt translations --- Contributing.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Contributing.md b/Contributing.md index 3009a086..e1086de7 100644 --- a/Contributing.md +++ b/Contributing.md @@ -380,11 +380,16 @@ In addition to that we utilise one of the user-defined levels as: ## Use fstrings, not modulo-formatting or .format -[fstrings](https://www.python.org/dev/peps/pep-0498/) are new in python 3.6, and allow for string interpolation rather -than more opaque formatting calls. +[fstrings](https://www.python.org/dev/peps/pep-0498/) are new in python 3.6, +and allow for string interpolation rather than more opaque formatting calls. -As part of our flake8 linting setup we have included a linter that warns when you use either `%` or `.format` on string -literals. +As part of our flake8 linting setup we have included a linter that warns when +you use `%` on string literals. + +`.format()` won't throw flake8 errors, **but only because it's still the +best way to handle [untranslated words](./docs/Translations.md#call-_) +in otherwise translated phrases**. Thus, we allow this, and only this, use of +`.format()` for strings. ---