From 0f97838381d7c6d5f30d0b9b2f39447a559d10d2 Mon Sep 17 00:00:00 2001 From: LB Johnston Date: Tue, 30 May 2023 08:31:42 +1000 Subject: [PATCH] Documentation - revise usage of e.g. - Replace one usage of 'eg' with more suitable alternatives - As per guidelines https://docs.wagtail.org/en/stable/contributing/general_guidelines.html#latin-phrases-and-abbreviations --- docs/advanced_topics/accessibility_considerations.md | 2 +- docs/advanced_topics/streamfield_migrations.md | 4 ++-- docs/contributing/first_contribution_guide.md | 6 +++--- docs/reference/pages/panels.md | 2 +- docs/releases/5.1.md | 2 +- docs/topics/snippets/features.md | 4 ++-- wagtail/admin/tests/test_edit_handlers.py | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/advanced_topics/accessibility_considerations.md b/docs/advanced_topics/accessibility_considerations.md index 648cd771b118..53a6fa17a433 100644 --- a/docs/advanced_topics/accessibility_considerations.md +++ b/docs/advanced_topics/accessibility_considerations.md @@ -143,7 +143,7 @@ By default, the checker includes the following rules to find common accessibilit - `link-name`: `` link elements must always have a text label. - `p-as-heading`: This rule checks for paragraphs that are styled as headings. Paragraphs should not be styled as headings, as they don’t help users who rely on headings to navigate content. -To customise how the checker is run (e.g. the rules to test), you can define a custom subclass of {class}`~wagtail.admin.userbar.AccessibilityItem` and override the attributes to your liking. Then, swap the instance of the default `AccessibilityItem` with an instance of your custom class via the [`construct_wagtail_userbar`](construct_wagtail_userbar) hook. +To customise how the checker is run (such as what rules to test), you can define a custom subclass of {class}`~wagtail.admin.userbar.AccessibilityItem` and override the attributes to your liking. Then, swap the instance of the default `AccessibilityItem` with an instance of your custom class via the [`construct_wagtail_userbar`](construct_wagtail_userbar) hook. The following is the reference documentation for the `AccessibilityItem` class: diff --git a/docs/advanced_topics/streamfield_migrations.md b/docs/advanced_topics/streamfield_migrations.md index 4a10597f7ed8..c4d2c3371a95 100644 --- a/docs/advanced_topics/streamfield_migrations.md +++ b/docs/advanced_topics/streamfield_migrations.md @@ -226,7 +226,7 @@ If you change the block definition of a StreamField on a model that has existing A StreamField is stored as a single column of JSON data in the database. Blocks are stored as structures within the JSON, and can be nested. However, as far as Django is concerned when generating schema migrations, everything inside this column is just a string of JSON data. The database schema doesn’t change - regardless of the content/structure of the StreamField - since it is the same field type before and after any change to the StreamField's blocks. Therefore whenever changes are made to StreamFields, any existing data must be changed into the new required structure, typically by defining a data migration. If the data is not migrated, even a simple change like renaming a block can result in old data being lost. -Generally, data migrations are performed manually by making an empty migration file and writing the forward and backward functions for a `RunPython` command. These functions handle the logic for taking the previously saved JSON representation and converting it into the new JSON representation needed. While this is fairly straightforward for simple changes (e.g. renaming a block), this can easily get very complicated when nested blocks, multiple fields, and revisions are involved. +Generally, data migrations are performed manually by making an empty migration file and writing the forward and backward functions for a `RunPython` command. These functions handle the logic for taking the previously saved JSON representation and converting it into the new JSON representation needed. While this is fairly straightforward for simple changes (such as renaming a block), this can easily get very complicated when nested blocks, multiple fields, and revisions are involved. To reduce boilerplate, and the potential for errors, `wagtail.blocks.migrations` provides the following: @@ -579,7 +579,7 @@ The value passed to `apply` when the matched block is a ListBlock would look lik #### Making structural changes -When making changes involving the structure of blocks (eg: changing block type), it may be necessary to operate on the block value of the parent block instead of the block to which the change is made, since only the value of a block is changed by the `apply` operation. +When making changes involving the structure of blocks (changing the block type for example), it may be necessary to operate on the block value of the parent block instead of the block to which the change is made, since only the value of a block is changed by the `apply` operation. Take a look at the implementation of `RenameStreamChildrenOperation` for an example. diff --git a/docs/contributing/first_contribution_guide.md b/docs/contributing/first_contribution_guide.md index 29bdaa12dddd..599b0b51f93d 100644 --- a/docs/contributing/first_contribution_guide.md +++ b/docs/contributing/first_contribution_guide.md @@ -149,7 +149,7 @@ Finally, before 'claiming' check you can do the following; #### Checklist (for a candidate issue) ```markdown -- [ ] Confirm that there is not someone actively working on it (e.g. PR or comments in the last ~2 months) +- [ ] Confirm that there is not someone actively working on it (no recent PR or comments in the last ~2 months) - [ ] Ensure you can reproduce the problem/scenario in your local version of Wagtail - [ ] Ensure that you feel confident to write a unit test (if it's a code change) to validate that the solution **is** implemented ``` @@ -309,11 +309,11 @@ If you have done all of that and think you can give it a go just a comment with 0. The fix or feature you are working on 1. Tests 2. Linted code (we make use of [pre-commit](https://pre-commit.com/). You can run all formatting with `make format`) -3. Updated documentation where relevant (e.g. when adding a new feature) +3. Updated documentation where relevant (such as when adding a new feature) ### What if I fix multiple issues in the same pull request (PR) -It is best to avoid fixing more than one issue in a single pull request, unless you are a core contributor or there is a clear plan that involves fixing multiple things at once. Even then, it is usually a bad idea as it makes it harder for your pull request to be reviewed and it may never get merged as it's too complex. This is especially true for completely unrelated issues (e.g. a documentation fix for translators and a bug fix for StreamField), it is always best to create two branches and then two separate pull requests. +It is best to avoid fixing more than one issue in a single pull request, unless you are a core contributor or there is a clear plan that involves fixing multiple things at once. Even then, it is usually a bad idea as it makes it harder for your pull request to be reviewed and it may never get merged as it's too complex. This is especially true for completely unrelated issues such as a documentation fix for translators and a bug fix for StreamField. It is always best to create two branches and then two separate pull requests. ### When do I need to write unit tests for a pull request (PR)? diff --git a/docs/reference/pages/panels.md b/docs/reference/pages/panels.md index 6cf2195da036..8dd100357287 100644 --- a/docs/reference/pages/panels.md +++ b/docs/reference/pages/panels.md @@ -43,7 +43,7 @@ Here are some built-in panel types that you can use in your panel definitions. T Allows you to prevent a model field value from being set or updated by editors. - For most field types, the field value will be rendered in the form for editors to see (along with field's label and help text), but no form inputs will be displayed, and the form will ignore attempts to change the value in POST data (e.g. by injecting a hidden input into the form HTML before submitting). + For most field types, the field value will be rendered in the form for editors to see (along with field's label and help text), but no form inputs will be displayed, and the form will ignore attempts to change the value in POST data. For example by injecting a hidden input into the form HTML before submitting. By default, field values from ``StreamField`` or ``RichTextField`` are redacted to prevent rendering of potentially insecure HTML mid-form. You can change this behaviour for custom panel types by overriding ``Panel.format_value_for_display()``. diff --git a/docs/releases/5.1.md b/docs/releases/5.1.md index f04ef292c8e8..42a45e39444f 100644 --- a/docs/releases/5.1.md +++ b/docs/releases/5.1.md @@ -79,7 +79,7 @@ This feature was developed by Aman Pandey as part of the Google Summer of Code p ### Bug fixes - * Prevent choosers from failing when initial value is an unrecognised ID, e.g. when moving a page from a location where `parent_page_types` would disallow it (Dan Braghis) + * Prevent choosers from failing when initial value is an unrecognised ID such as when moving a page from a location where `parent_page_types` would disallow it (Dan Braghis) * Move comment notifications toggle to the comments side panel (Sage Abdullah) * Remove comment button on InlinePanel fields (Sage Abdullah) * Fix missing link to `UsageView` from `EditView` for snippets (Christer Jensen) diff --git a/docs/topics/snippets/features.md b/docs/topics/snippets/features.md index 94d3f40a5428..f15a4f61491c 100644 --- a/docs/topics/snippets/features.md +++ b/docs/topics/snippets/features.md @@ -113,7 +113,7 @@ class Advert(index.Indexed, models.Model): ## Saving revisions of snippets -If a snippet model inherits from {class}`~wagtail.models.RevisionMixin`, Wagtail will automatically save revisions when you save any changes in the snippets admin. In addition to inheriting the mixin, it is recommended to define a {class}`~django.contrib.contenttypes.fields.GenericRelation` to the {class}`~wagtail.models.Revision` model as the {attr}`~wagtail.models.RevisionMixin.revisions` attribute so that you can do related queries. If you need to customise how the revisions are fetched (e.g. to handle the content type to use for models with multi-table inheritance), you can define a property instead. For example, the `Advert` snippet could be made revisable as follows: +If a snippet model inherits from {class}`~wagtail.models.RevisionMixin`, Wagtail will automatically save revisions when you save any changes in the snippets admin. In addition to inheriting the mixin, it is recommended to define a {class}`~django.contrib.contenttypes.fields.GenericRelation` to the {class}`~wagtail.models.Revision` model as the {attr}`~wagtail.models.RevisionMixin.revisions` attribute so that you can do related queries. If you need to customise how the revisions are fetched (for example, to handle the content type to use for models with multi-table inheritance), you can define a property instead. For example, the `Advert` snippet could be made revisable as follows: ```python # ... @@ -237,7 +237,7 @@ If you use the scheduled publishing feature, make sure that you run the [`publis Publishing a snippet instance requires `publish` permission on the snippet model. For models with `DraftStateMixin` applied, Wagtail automatically creates the corresponding `publish` permissions and display them in the 'Groups' area of the Wagtail admin interface. For more details on how to configure the permission, see [](permissions_overview). ```{warning} -Wagtail does not yet have a mechanism to prevent editors from including unpublished ("draft") snippets in pages. When including a `DraftStateMixin`-enabled snippet in pages, make sure that you add necessary checks to handle how a draft snippet should be rendered (e.g. by checking its `live` field). We are planning to improve this in the future. +Wagtail does not yet have a mechanism to prevent editors from including unpublished ("draft") snippets in pages. When including a `DraftStateMixin`-enabled snippet in pages, make sure that you add necessary checks to handle how a draft snippet should be rendered (for example, by checking its `live` field). We are planning to improve this in the future. ``` (wagtailsnippets_locking_snippets)= diff --git a/wagtail/admin/tests/test_edit_handlers.py b/wagtail/admin/tests/test_edit_handlers.py index 4965d4b5c5d1..24c382d678b4 100644 --- a/wagtail/admin/tests/test_edit_handlers.py +++ b/wagtail/admin/tests/test_edit_handlers.py @@ -1834,7 +1834,7 @@ def test_users_can_edit_comment_positions(self): comment_form = form.formsets["comments"].forms[0] self.assertTrue(comment_form.is_valid()) # Users can change the positions of other users' comments within a field - # eg by editing a rich text field + # e.g. by editing a rich text field @freeze_time("2017-01-01 12:00:00") def test_comment_resolve(self):