In 61c1d35f17 I added a
PluginOutlet to AdminPluginConfigPage. This was intended to be
used as a way to render actions buttons inside the header of
a plugin that has a custom admin UI page. This worked, but
since the outlet was generically named, as soon as one plugin
used it the button would show on all plugins.
This fixes the immediate issue by naming the outlet based
on the plugin, then having each plugin specify their own
outlet to render into. There may be a nicer way to do this,
but for now this stops the bleeding.
This commit introduces a feature that allows an admin to delete a user's
associated account. After deletion, a log will be recorded in staff
actions.
ref=t/136675
In our test suite, we sometimes see ChunkLoadErrors. This plugin should cause those failed requests to be retried seamlessly. It'll also help clients with flaky internet connections in production.
the radical change in the implementation doesn't stem from the glimmer migration, but rather the fact that previously the component was single-use – changing any of its args didn't (and couldn't) be reflected because hljs was replacing the nodes so all the ember bookkeeping was gone.
Co-authored-by: David Taylor <david@taylorhq.com>
There is a risk of overriding and then deleting a prop of the context in case of a naming clash between localName and that prop, e.g.
```js
class Test {
item = "foo";
items = [1, 2];
}
const template = `
{{#each items as |item|}}
{{item}}
{{/each}}
`;
const compiledTemplate = compile(template);
const object = new Test();
// object.item === "foo"
const output = compiledTemplate(object, RUNTIME_OPTIONS);
// object.item === undefined
```
…but I think we can accept this risk and just be careful.`#each` isn't widely used in hbr anyway (as proven by the other long-standing and recently fixed bug) and hbr is on its way out anyway.
his is a new feature that lets admins dismiss notices from the dashboard. This helps with self-service in cases where a notice is "stuck", while we work on provisions to prevent "sticking" in the first place.
In some very rare cases, the header element doesn't yet have the bg
when this code is run. This PR adds a simple retry mechanism.
No tests because this relies on specific load timing from the browser.
Previously shortcuts added to toolbar buttons will automatically use the same action assigned to the button when clicked. This PR adds an additional optional key that can be passed when creating a new toolbar button: shortcutAction which allows for passing a custom action for the keyboard shortcut. This way a button can have a specific action when a keyboard shortcut is pressed that's different from when the button is clicked.
Followup to e25578d702
Using execCommand to replace the entire contents of the textarea is very slow for larger posts (it seems the browser does a reflow after every 'virtual keypress'.
This commit updates the `replaceText` function to be more surgical with its `insertAt` calls. Now it only selects & replaces the characters which are actually being replaced.
Previously for reviewables that could be claimed, we positioned
the "you can claim / you must claim" message and button underneath
the "Is there something wrong with this post?" message but _before_
the reviewable action buttons like Yes/No/Ignore. This was a confusing
flow.
This commit fixes the issue, and also makes it so if claiming is
required and the reviewable has not been claimed, we don't show
the "Is there something wrong with this post?" which was showing
with no buttons.
Followup 5a8e7c5f29
The admin report results need to be side by side
with the filter for the report, which sits on the
right. The previous commit made it stacked.
Currently, when the custom flag has the same name as the system flag (which is disabled) then it is not displayed. To fix the problem, `custom_` prefix as `name_key` is used to distinguish between the system and the custom flag.
I considered writing a migration to fix existing custom flags name key. However, at the end of migration I would need to run rails code to reset cache `Flag.reset_flag_settings!`. I decided to skip that step as it is a very edge case. If someone has the same flag name as the system flag, then all they have to do is edit the flag and click save.
In addition, I made 2 small fixes:
- edit flag title was missing translation;
- flag form UI was not showing that description is the required field.
* FIX: add "in:first" to user summary category search
The "in:first" parameter was added to the search parameters for the topic count in the user summary category search.
This ensures that the search results focus specifically on the first posts in each topic, so only topics are returned.
Meta topic: https://meta.discourse.org/t/summary-page-by-category-topic-links/215848
* add tests
Provided by @natsw
This commit converts the current chat plugin UI into the
new "show plugin" UI already followed by AI and Gamification.
In the process, I also:
* Made a dedicated /new route to create new webhooks
* Converted the webhook form to FormKit
* Made some fixes and improvements to the `AdminPluginConfigPage`, `AdminPageHeader`,
and `AdminPageSubheader` generic components, so more plugins can
adopt the UI guidelines too. This includes adding a header outlet so plugins
can add action buttons to the plugin show page header.
* Fixes the submit button loading state for FormKit (by Joffrey)
---------
Co-authored-by: Joffrey JAFFEUX <j.jaffeux@gmail.com>
Followup 14b436923c
On the standalone Site Traffic report page, we also need
to hide the 'other' and 'crawler' pageviews by default
like we do on the admin dashboard.
### UI changes
All of the UI changes described are gated behind the `use_legacy_pageviews`
site setting.
This commit changes the admin dashboard pageviews report to
use the "Consolidated Pageviews with Browser Detection" report
introduced in 2f2da72747 with
the following changes:
* The report name is changed to "Site traffic"
* The pageview count on the dashboard is counting only using the new method
* The old "Consolidated Pageviews" report is renamed as "Consolidated Legacy Pageviews"
* By default "known crawlers" and "other" sources of pageviews are hidden on the report
When `use_legacy_pageviews` is `true`, we do not show or allow running
the "Site traffic" report for admins. When `use_legacy_pageviews` is `false`,
we do not show or allow running the following legacy reports:
* consolidated_page_views
* consolidated_page_views_browser_detection
* page_view_anon_reqs
* page_view_logged_in_reqs
### Historical data changes
Also part of this change is that, since we introduced our new "Consolidated
Pageviews with Browser Detection" report, some admins are confused at either:
* The lack of data before a certain date , which didn’t exist before
we started collecting it
* Comparing this and the current "Consolidated Pageviews" report data,
which rolls up "Other Pageviews" into "Anonymous Browser" and so it
appears inaccurate
All pageview data in the new report before the date where the _first_
anon or logged in browser pageview was recorded is now hidden.
This upgrade is designed to be fully backwards-compatible. Any icon names which have changed will be automatically remapped to the new name. For now, this will happen silently. In future, once core & official themes/plugins have been updated, we will start raising deprecation errors to help theme/plugin authors update their code.
Extracted from https://github.com/discourse/discourse/pull/28715
Announcement at https://meta.discourse.org/t/were-upgrading-our-icons-to-font-awesome-6/325349
Co-authored-by: awesomerobot <kris.aubuchon@discourse.org>
* FEATURE: Log tag group changes in staff action log
This commit records every change (add, change, delete) to a tag group in
the staff action log.
It uses a modal that was originally called ThemeChangeModal to display
changes, allowing staffs to see the specific changes clearly. The modal
is renamed to StaffActionLogChangeModal in this PR.
ref: https://meta.discourse.org/t/-/325011/14
Co-authored-by: Keegan George <kgeorge13@gmail.com>
This commit adds a link to the top of the new /about page, shown to admins only, to allow them to easily navigate to `/admin/config/about` where they can edit the /about page.
Internal topic: t/137546.
Static pages such as /about, /faqs, /tos etc. currently overflow horizontally on some Android devices (reproducible on Samsung Galaxy A11). It seems like the `width: 100%` property on `.body-page` is what causing the problem, and removing it doesn't seem to break anything on the various devices that I've tested (desktop, iOS, Android).
* UX: Add a description about badges
* WIP: Apply admin UI guidelines
* FIX: Add routeModels to dbutton
Allows routeModels to be passed to a DButton along
with route, so we can use them as a LinkTo replacement
in more places.
Also fix up badges admin page header.
* UX: Reorder action buttons
* UX: Change header hierarchy to better align page's content structure
* UX: Update copy and remove unnecessary UI elements
* UX: Adjust header's icon spacing
* UX: Fix the header action buttons on mobile
* Apply prettier
---------
Co-authored-by: Martin Brennan <martin@discourse.org>
We need to start printing deprecation notices when the `show_in_ui` argument is used because it works only for the old about page which will be removed soon. For the new about page, we've introduced a new API `addAboutPageActivity` which is more flexible than a true/false argument on the server side.
Internal topic: t/136551.
- Uses `helper.renderGlimmer` with GJS to render the `<Poll` component without any widgets
- Moves some logic into component, so that only `@post`, `@poll` and `@titleHTML` need to be passed into the component (no more 'attrs')
- Updates `modifyClass` calls to modern syntax
- Replaces observer in `Post` model with a native setter & tracked property
- Replaced Poll EmberObject instances with TrackedObject
- Updated component tests with new arguments
- Updated some tests to qunit-dom
- Fixed up core `repliesBelow` and `repliesAbove` logic to create post models properly. Previously it was passing 'transformed' versions of posts into the model, which doesn't make sense.
Currently, categories support designating only 1 group as a moderation group on the category. This commit removes the one group limitation and makes it possible to designate multiple groups as mods on a category.
Internal topic: t/124648.
* DEV: Convert card-contents-base from mixin to base class
This allows us to convert it to native class syntax
Mixins are essentially deprecated, and will not be receiving native class syntax support. In this case, there is no real need for it to be a mixin, so a base class makes sense.
The old /about page has 3 plugin outlets: one after the description, one after the admins list, and one after the mods list. These outlets translate cleanly to the new /about page, so we should add them to it to make plugins/themes compatible with the new page.
This will bring significant improvements to install speed & storage requirements. For information on how it may affect you, see https://meta.discourse.org/t/324521
This commit:
- removes the `yarn.lock` and replaces with `pnpm-lock.yaml`
- updates workspaces to pnpm format
- adjusts package dependencies to work with pnpm's stricter resolution strategy
- updates Rails app to load modules from more specific node_modules directories
- adds a `.pnpmfile` which automatically cleans up old yarn-managed `node_modules` directories
- updates various scripts to call `pnpm` instead of `yarn`
- updates patches to use pnpm's native patch system instead of patch-package
- adds a patch for licensee to support pnpm
Originally, we assumed that the href passed to the NavigationItem must
not have URLParams, and roughly appended URLParams such as
`?order=created` to the end. This will result in something like
`/latest?state=my_votes?order=created` (note the double question mark
here), for example the discourse-topic-voting plugin
This commit modifies the logic for appending URLParams to the end,
ensuring that the original URL parameters are preserved.
A new setting attribute is used to define the areas (separated by `|`).
In addition, endpoint `/admin/config/site_settings.json` accepts new `filter_area` data.
A previous refactor has moved this function in the controller instead of the route making it inaccessible to the modal.
This commit is fixing this and also adding a spec.
In particular, this allows us to use gjs `<template>` for RenderGlimmer, registerWidgetShim, and decorateCooked's `helper.renderGlimmer`.
```js
// Simple component class:
registerWidgetShim(
"render-glimmer-test-component-shim",
"div.initial-wrapper-class",
SimpleComponent
);
```
```gjs
// Or an inline `<template>`
registerWidgetShim(
"render-glimmer-test-component-shim",
"div.initial-wrapper-class",
<template>Hello world</template>
);
```
We're working to remove all decorators from object-literal-properties. This commit refactors all initializers which were using these decorators into classes, where decorators are allowed. Also adds cleanup logic to the local-dates initializer, which was previously missing.
This will avoid warnings: "The code generator has deoptimised the styling of {path} as it exceeds the max of 500KB."
Should also provide a tiny improvement in build times
This commit introduces a little bit of duplication
since the old plugin UIs not using the new plugin show
page look different from ones like AI and Gamification
which have been converted. We can use the new admin
header component on the plugins list, but for the other
pages we are manually rendering a breadcrumb trail and
the list of plugin tabs.
Over time as we convert more plugins to use the new UI
guidelines and show page we can get rid of this duplication.
This commit adds a description for all the auto groups
which will be shown in the group list and show group
pages, which will help admins understand their purpose
better.
Also adds an indicator with a tooltip to explain what
the auto groups are on the group show page.
We were not updating `searchTerm` when changing the input which was making us always send an empty q parameter.
This commit is also adding tests for:
- initial url with q param
- filtering the bookmarks through the input
I mistakenly replaced these with `@equal`, thinking the behavior was the same. It's not. `@propertyEqual` compares two properties, while `@equal` compares a single property with a constant.
Changes made using the ember-native-class-codemod, plus some manual tweaks
Also ensures our implicit injections applied to the prototype immediately. Without this, they will only be applied on the next `.extend()` call, which is now later than the first native-class extension.
When the tooltip items are tooltipItem = [{parsed: {y:12} }, {parsed: {y:10} } ], reducing without a initial value as a number would result in Javascript thinking it is a string. Thanks, Javascript!
There are no tests here yet since this makes use of an external library Chart.js.
Why all the manual setting of `width` and `height`? Without it all ace editors were 0x0, invisible.
Why didn't it affect the tests before? ace-editor tests only confirms that there is an element, theme-settings-editor tests were effectively unit tests before 7317b5a, fk-code test avoids interacting with ace.
Makes it easier to reach the group from the category security
tab, and moves the trash button to the right to avoid misclicks.
Also converts the category permission row to gjs
This commit changes the cutoff number for the admins and mods lists on the new /about page from 12 to 6. If the admins or mods lists are bigger than 6, the about page will display the 6 most recently seen admins/mods, and tuck the rest away behind a "view more" button.
Given we are a single-page-app, we hijack the browser's default behavior
for keyboard shortcuts like End because on long topics (20+ posts) we
need to load the last post before really reaching the end of the page.
However, when the last post is already rendered, the End shortcut
currently does nothing, it takes the user to the start of the last post.
If that post is too long, the user will have to scroll down manually.
This change ensures that if the last post of a topic is already rendered
(whether it is in the viewport or not), pressing End will take the user
to the very bottom of the page.
Note for the reviewer: the test added here is for the general case, it
is too hard to test the case where the last post is already rendered,
that isn't covered here.
In FormKit you can add error on an existing field existing in the DOM, but you can also set an arbitrary error on a virtual field not existing in the DOM.
When revalidating existing data, we are only resetting real fields. This commit adds `removeError(name)` to allow you to manually manage virtual fields. `removeError` is available in the same helpers where `addError` is available.
<!-- NOTE: All pull requests should have tests (rspec in Ruby, qunit in JavaScript). If your code does not include test coverage, please include an explanation of why it was omitted. -->
Prior to this fix using:
- `replaceText(...)`
- `selectText(..., ..., { scroll: true})`
Wouldn't have the expected behaviour as the scroll from selectText will attempt to save the scroll position and restore it AFTER the replacement happened. This commit allows scroll to be a Boolean or a Number, when a number, it will be used to restore the scrollTop position.
I tried to write tests for this specific behavior but couldn't reproduce the issue in tests.
A follow-up to dd1abf91ef.
Because `ember-cli-deprecation-workflow` relied on `@ember/string` 3.1.1, that was the effective version used in the app.
Turns out there's a compatiblity issue with 4.0.0. Let's lock it to 3.x so we can easily update deprecation-workflow and then we can look into the ember/string issue.
All those addons import it but didn't have it in their package.jsons. And because the only thing that had it as a dependency (ember-cli-deprecation-workflow) removed it in the latest version, the build breaks.
File it under: a problem we wouldn't have with pnpm :P
In GroupRequestsController, request_count is incorrectly written as
user_count, which causes group member requests to be loaded infinitely
when user_count is greater than request_count.
When searching for site texts for admin using the english
version of the text, previously we would show the english
version in the results _even if_ there was another locale
translated version available when a locale was selected
from the dropdown.
This commit adds a "Only show results in selected locale"
checkbox option which will instead make it so the results
shown are in the target locale, making it easier for translators
to tell when there is actually translations vs. missing tranlsations.
If there is a codec issue or something trying to process a video file
for thumbnail generation, uploads could hang indefinitely. This fix
ensures that we continue the upload process even if we encounter an
error trying to generate a thumbnail for it.
If you’re viewing a tag and you switch to a different tag via the sidebar or the tags dropdown, after expanding the info section of the tag page via the wrench button, the info section keeps showing the previous tag's details instead of the new one.
This happens because the tag info section makes an ajax request to load the tag's details, and this request is made inside the `didInsertElement` hook which is only fired once when the component is rendered. To fix this, we need to set the result from the ajax request to null and add a `didUpdateAttrs` hook to trigger another request to load the info of the new tag.
Internal topic: t/134809.
This change is preventing the "is dirty check" from happening when clicking delete on this form. This was not good UX and was also causing bugs by leaving the form in a unexpected state.
Previous to this change there is no clean way to apply keyboard shortcuts
to things such as "add poll" and other hidden options in the toolbar
This allows shortcuts to be specified similar to how they are on the toolbar
Co-authored-by: Joffrey JAFFEUX <j.jaffeux@gmail.com>
If we don't get a `videoWidth` back for a video don't try and generate a
thumbnail for it.
Also as part of this change I switched getImageData, the function
throwing the error, to use video.videoWidth instead of canvas.width
because it's very likely we were setting canvas.width too early before
the width could be read. Now that we are reading the value inside of the
setTimeout hopefully we will actually have a width. Just incase we don't
detect a width we will now exit early instead of throwing an error.
We only need to check for `0` and not null because the value is an
integer and will always return a 0 if it can't be read. https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/videoWidth
See https://meta.discourse.org/t/322363
This lays the groundwork for converting SelectKit subclasses to native class syntax. This commit is designed to be entirely backwards-compatible, so it should not affect any existing subclasses.
Of interest:
- Any properties which are designed to be overridden by subclasses are implemented using a local `@protoProp` decorator. That means they are applied to the prototype, so that they can be overridden in subclasses by both legacy `.extend()` prototype extensions, and by modern native-class fields.
- New class decorators are introduced: `@selectKitOptions` and `@pluginApiIdentifiers`. These are native class versions of the legacy `concatenatedProperties` system. This follows the pattern Ember has introduced for `@className`, `@classNameBindings`, etc.
This would cause the infamous error:
```
index.js:118 Uncaught (in promise)
Error: Assertion Failed: You attempted to update `href` on `<ExtraNavItem:ember384>`, but it had already been used previously in the same computation.
```
Moreover, set didnt seem necessary here.
Followup 1446596089
The link to inform admins that restore is disabled
was not correct. This fixes it and also changes it
to go to /admin/backups/settings
This commit changes the custom flags admin config area
to use the AdminPageHeader component and conforms
to the new admin UI guidelines. Also makes some slight
modifications to the reusable components to handle using
a @route for an action button.
This commit implements 2 new metrics/stats in the /about page for the _estimated_ numbers of unique visitors from the EU and the rest of the world. This new feature is currently off by default, but it can be enabled by turning on the hidden `display_eu_visitor_stats` site settings via the rails console.
There are a number of assumptions that we're making here in order to estimate the number of unique visitors, specifically:
1. we're assuming that the average of page views per anonymous visitor is similar to the average number of page views that a logged-in visitor makes, and
2. we're assuming that the ratio of logged in visitors from the EU is similar to the ratio of anonymous visitors from the EU
Discourse keeps track of the number of both logged-in and anonymous page views, and also the number of unique logged-in visitors and where they're from. So with those numbers and the assumptions above, we can estimate the number of unique anonymous visitors from the EU and the rest of the world.
Internal topic: t/128480.
This commit introduces a new frontend API to add custom items to the "Site activity" section in the new /about page. The new API is called `addAboutPageActivity` and it works along side the `register_stat` serve-side API which serializes the data that the frontend API consumes. More details of how the two APIs work together is in the JSDoc comment above the API function definition.
Internal topic: t/128545/9.
This commit improves the hilight-ing of mentions in posts and chat messages.
- `@here` and `@all` will generate a `<a class="mention --wide">`
- bots will generate a `<a class="mention --bot">`
- current user will generate a `<a class="mention --current">`
To achieve this change the following value transformer has been added: "mentions-class". It will be run in posts and chat messages after the mention is rendered.
A bug were bots were not considered in mentioned users has also been fixed as part of this PR.
This commit fixes a bug where the silence button is incorrectly displayed on the admin page of a staff user. It's not actually possible to silence a staff user because the backend correctly prevents it, but the frontend isn't checking if the button should be displayed.
Another small bug that this commit fixes is the similar users list not showing up inside the silence/suspend modals due to also a bug in the frontend.
I've also changed the way similar users are loaded so that they're not returned by the `admin/users#show` endpoint anymore and moved them into a new endpoint that the penalize modals (suspend and silence) can call directly to retrieve the list of users. This is done because the similar users list is never shown on the admin user page (`/admin/users/:user_id/:username`); they're only needed when the suspend or silence modals are opened.
Internal topic: t/130014.
This is a variation on bc3e8a9963cf9a64d114ec751c875025af169690, which was reverted due to issues on iOS. Safari's "in response to user action" check cannot follow the `runAfterFramePaint` chain of interaction -> requestAnimationFrame -> messageChannel, and so some sensitive browser APIs (e.g. clipboard, upload, etc.) were blocked.
This commit is similar, but uses `next()` instead of `runAfterFramePaint()`. The result seems the same, but doesn't have the same issue on iOS.
The chat-emoji-picker change was required to resolve a test failure. The emoji picker has never closed-on-scroll on desktop, so there is no user-facing change in behavior.
This commit converts the Backups page in the admin interface
to follow our new admin interface guidelines.
As part of this work, I've also made `AdminPageHeader` and `AdminPageSubheader`
components that can be reused on any admin page for consistency, that handle
the title and action buttons and also breadcrumbs.
Also renamed `AdminPluginFilteredSiteSettings` to `AdminFilteredSiteSettings` since
it can be used generally to show a subset of filtered site settings, not only
settings for a plugin. Not sure if it's ideal to have to define a new route for this
for every config area, but not sure how else to do it right now.
This commit adds a blue dot next to the "What's New"
link in the admin sidebar if the user has not seen the
new features yet, as a followup to 3e5976f843
which removed the tab on the dashboard that had this same
functionality.
When the admin visits the "What's New" page they count
as having seen all the features straight away. This could
be something we want to change, but for now this keeps the
same functionality.
`routeAction` is testing at runtime that a route exists when in debug mode. However in the case of components tested in isolation there's no existing route which was causing an exception, this commit prevents this check in this case as it's irrelevant.
Long code is considered 1000 characters atm. 10000+ characters would take seconds due to how highlightjs will consider every installed lang before choosing the best candidate.
Move it into the preceding `dl` element and remove the `div` wrapper.
The two plugins that use this outlet:
* d-follow - actually jumps through hacky hoops to get its elements into that `dl` anyway
* d-gamification - would look better if its element was in that `dl`
We used to show New Features in a tab on the dashboard,
but this could get pushed down the page especially on
our hosting. In 043117ca13
we made a separate What's New page, so this commit removes
the dashboard tab and changes the admin notification to
send the admin to /admin/whats-new instead of the dashboard
tab.
This commit fixes a number of bugs in `file_size_restriction` settings and does a little of refactoring to reduce duplicated code in site setting types (the refactoring is necessary to fix one of the bugs).
The bugs in `file_size_restriction` settings that are fixed in this commit:
1. Save/cancel buttons next to a `file_size_restriction` setting are shown upon navigating to the settings page without changes being made to the setting
2. Cancel button that discards changes made to the setting doesn't work
3. Reset button that resets the setting to its default doesn't work
4. Validation error message isn't cleared when resetting/cancelling changes
To repro those bugs, navigate to `/admin/site_settings/category/files` and observe the top 2 settings in the page (`max image size kb` and `max attachment size kb`).
Internal topic: t/134726.
Desktop chat notification sounds have stopped working on most desktop browsers.
This is due to Notifications API being disabled when Push Notifications are supported in the browser, which means that we never iterate on the desktopNotificationHandlers and trigger the callback since we return early.
When browsing through a sidebar with this feature enabled (i.e. admin, or docs), it's weird to have the scroll jump around when you click an item. This commit adds a check, so that we only `scrollIntoView` for items which are not already in the viewport.
Followup to b7cce1a0dc
We changed the design of the member access wizard step to use toggle groups instead of switches. To support existing designs for notices, we need another plugin outlet.
0 is falsy in JavaScript, so the original code would treat 0 as if it
were not input. This unique exception was added to prevent 0 from being
treated as empty input.
This commit fixes a bug in the redesigned about page where if there's no banner image configured for the page, the top of the page where the banner goes is occupied with large white space. Additionally, this commit also fixes a related bug in the admin config area for the /about page where it's not possible to remove the uploaded banner image.
`defaultCategoryLinkRenderer` is using a fake category object which doesn’t have access to the functions and getters of category model.
This had been incorrectly set in c197daa04c
As we don't get a real category object, we have to call the transformers manually and also pass the fake category object as context, this is not ideal as people might try to access properties in the transformer which are not available on the category object given they will be different based on the context. Hopefully one day this helper and all the chain can be refactored to use a real category model.
This commit also adds tests for these two properties in the category-link helper.
<!-- NOTE: All pull requests should have tests (rspec in Ruby, qunit in JavaScript). If your code does not include test coverage, please include an explanation of why it was omitted. -->
