Skip to content

Commit 16dc580

Browse files
committed
Remove/move items unrelated to Git from the Git commit cheat sheet
* Remove the following: - Testing instructions bit - It's already covered in /general/development/process/testing - Removing strings - Also already covered in the String deprecation docs. * Move the `Introducing new strings` section under the `Language` section of the Coding style docs.
1 parent 076be4f commit 16dc580

2 files changed

Lines changed: 28 additions & 54 deletions

File tree

docs/guides/git/cheatsheet.md

Lines changed: 0 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -54,56 +54,6 @@ Rebase all the commits into a single commit, and add the mention `Co-authored-by
5454

5555
Check out this commit from [MDL-64000](https://github.com/moodle/moodle/commit/fbb2196) as an example.
5656

57-
## Provide clear and operational instructions to test your patch
58-
59-
In the tracker issue, please describe how the change can be tested. Please avoid vague phrases like "Make sure there is no regression in the core" or "Test all places where XXX is used". Also, try to avoid requiring resources that are really difficult to gather, if possible - as in "Use production data from a server with 100.000+ students".
60-
61-
If you have permission, edit the tracker issue and put the testing instructions into the "Testing instructions" field. If you do not have permission to edit that field, then write them in a comment on the tracker issue.
62-
63-
It helps if you state your estimation of the testing difficulty so that testers can pick issues for them:
64-
65-
- **Easy:** (average community member should be able to test it) - can be tested pretty easily via the web interface only at a public test site
66-
- **Moderate:** (knowledgeable administrator should be able to test it) - requires local installation, for example to test some 1.9 -> 2.0 upgrade steps or some non-standard environment (for example MNet features, specific platform etc)
67-
- **Hard:** (development skills are required to test it) - for example may require data hacking at SQL level to simulate data corruption or modifying the code to reproduce the problem
68-
69-
<ValidExample title="Example testing instructions">
70-
71-
(Difficulty: Easy, requires teacher access to a course)
72-
73-
1. Log in as a teacher and go to a course
74-
2. Turn editing mode on
75-
3. TEST: Make sure that the control icons appear next to the activity titles
76-
4. Turn editing mode off
77-
5. TEST: Make sure that the control icons are not displayed now
78-
79-
</ValidExample>
80-
81-
## Introducing new strings
82-
83-
Firstly, think twice and try to think in a non-English language. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using get_string() for debugging messages that are likely to almost never appear. It is warmly recommended to let Helen review your strings before you submit them. This way we can keep the terminology and the style consistent. When introducing new strings, keep them alphabetically sorted. Using a self-descriptive names of the string identifier and the placeholder properties helps the translators to guess the context. Compare the following
84-
85-
```php
86-
$string['grade'] = 'Grade {$a}';
87-
```
88-
89-
with
90-
91-
```php
92-
$string['maxgradevalue'] = 'Grade {$a->value}';
93-
```
94-
95-
In the first case, it is pretty difficult to guess whether the "Grade" in the string is a noun (as in "Grade 12/30") or a verb (as in "Grade submission"). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.
96-
97-
Another good example of how _not_ to name string identifiers would be something like
98-
99-
```php
100-
$string['post'] = 'Post';
101-
```
102-
103-
Note that there is no clue if the "post" here is used as a noun (e.g. describing one particular forum post) or a verb (such as an action of posting into a forum). In many languages, the translation is different for either case.
104-
105-
See [Help strings](https://docs.moodle.org/dev/Help_strings) if you are introducing a new help string.
106-
10757
## Include AMOS script in the commit if needed
10858

10959
If you change the identifier of a string or split a string into two forks, provide a script for AMOS in the commit message. Since Moodle 2.0, the translations are kept on separated branches again. The AMOS plugin on the [Moodle Translation site](https://lang.moodle.org) tracks the changes in string files and automatically records modifications, additions and removals of strings. Therefore, strings can be re-worded freely on stable branches and should be removed from the main branch if they are not needed any more (do not remove strings from stable branches).
@@ -128,10 +78,6 @@ AMOS END
12878

12979
See [Automated Manipulation of Strings 2.0#AMOS script](/general/projects/api/amos#amos-script) for more details of the syntax. See [the log history](http://git.moodle.org/gw?p=moodle.git&a=search&h=HEAD&st=commit&s=AMOS+BEGIN) for actual usage examples.
13080

131-
## Removing strings
132-
133-
When a new feature completely replaces an existing feature, any strings which are no longer used should be removed from the code in the main branch. See [String deprecation](/general/projects/api/string-deprecation) for more information.
134-
13581
## Main version changes
13682

13783
If your commit requires a change to the main version number in `version.php` (and corresponding upgrade in `lib/db/upgrade.php`), you should increment that version number by `.01`, and let merge reviewers deal with merge conflicts (for example, if multiple people that week submit several `.01` updates).

general/development/policies/codingstyle/index.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -785,6 +785,34 @@ The dot operator may be used without any space to either side (as shown in the a
785785

786786
### Language strings
787787

788+
#### Introducing new strings
789+
790+
Firstly, think twice and try to think in a language other than English. Any string you introduce is supposed to be translated by translators who usually do it for free in their own time. Do not waste their time by using `get_string()` for debugging messages that are unlikely to appear in production. It is recommended to add the `ux_writing` label on the tracker issue so that Moodle HQ's UX team can review your strings in the patch. This way, we can keep the terminology and the style consistent.
791+
792+
When introducing new strings, keep them in alphabetical order. Using self-descriptive names for the string identifier and the placeholder properties helps translators infer the context. Compare the following:
793+
794+
```php
795+
$string['grade'] = 'Grade {$a}';
796+
```
797+
798+
with
799+
800+
```php
801+
$string['maxgradevalue'] = 'Grade {$a->value}';
802+
```
803+
804+
In the first case, it is pretty difficult to guess whether the "Grade" in the string is a noun (as in "Grade 12/30") or a verb (as in "Grade submission"). In many languages, the translation depends on it. The second case is more self-descriptive as it indicates that the placeholder will contain a value.
805+
806+
Another good example of how _not_ to name string identifiers would be something like
807+
808+
```php
809+
$string['post'] = 'Post';
810+
```
811+
812+
Note that there is no clue if the "post" here is used as a noun (e.g. describing one particular forum post) or a verb (such as an action of posting into a forum). In many languages, the translation is different for either case.
813+
814+
See [Help strings](https://docs.moodle.org/dev/Help_strings) if you are introducing a new help string.
815+
788816
#### Capitals
789817

790818
Capitals should only be used when:

0 commit comments

Comments
 (0)