From 0a187eae0ab33b460c538d7b2a90698796f22b70 Mon Sep 17 00:00:00 2001 From: Sabina Talipova Date: Mon, 31 Jul 2023 16:21:00 +1200 Subject: [PATCH 1/4] DOC Warnings about searchable_fields content --- en/02_Developer_Guides/00_Model/11_Scaffolding.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/en/02_Developer_Guides/00_Model/11_Scaffolding.md b/en/02_Developer_Guides/00_Model/11_Scaffolding.md index cab050a17..0aa91e54d 100644 --- a/en/02_Developer_Guides/00_Model/11_Scaffolding.md +++ b/en/02_Developer_Guides/00_Model/11_Scaffolding.md @@ -70,10 +70,13 @@ The `$searchable_fields` property uses a mixed array format that can be used to system. The default is a set of array values listing the fields. [info] -`$searchable_fields` will default to use the [`$summary_fields` config](#summary-fields) if not defined. This works fine unless -your `$summary_fields` config specifies fields that are not stored in the database. +`$searchable_fields` will default to use the [`$summary_fields` config](#summary-fields), excluding anything that isn't a database field (such as method calls) if not explicitly defined. [/info] +[warning] +If you define a `searchable_fields` configuration, _do not_ specify fields that are not stored in the database (such as methods), as this will cause an error. +[/warning] + ```php use SilverStripe\ORM\DataObject; From 51ad53f3332ee7f6f8ffed98bb08e92926eeb38a Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Mon, 24 Jul 2023 23:16:05 +1200 Subject: [PATCH 2/4] parent 1a73935fdecaa1cbeee0ad12986267d5c1e4a62f author Maxime Rainville 1690197365 +1200 committer Maxime Rainville 1690875014 +1200 DOC Add minor release policy --- en/05_Contributing/00_Issues_and_Bugs.md | 4 + .../06_Minor_release_policy.md | 93 +++++++++++++++++++ ...ted_Modules.md => 07_Supported_Modules.md} | 0 3 files changed, 97 insertions(+) create mode 100644 en/06_Project_Governance/06_Minor_release_policy.md rename en/06_Project_Governance/{06_Supported_Modules.md => 07_Supported_Modules.md} (100%) diff --git a/en/05_Contributing/00_Issues_and_Bugs.md b/en/05_Contributing/00_Issues_and_Bugs.md index ac332682a..c534397d1 100644 --- a/en/05_Contributing/00_Issues_and_Bugs.md +++ b/en/05_Contributing/00_Issues_and_Bugs.md @@ -64,6 +64,10 @@ Silverstripe CMS does not operate a *bug bounty* program. Review our [Managing Security Guidelines](managing_security_issues) guidelines to understand what happens once a vulnerability is reported. +Silverstripe CMS aims to ship security patches at pre-defined intervals when those issues are not actively exploited in the wild. + +Review the [Security patch windows](../Project_Governance/Minor_release_policy#security-patch-windows) section of our minor release policy for more details. + ## Sharing your Opinion * [forum.silverstripe.org](http://forum.silverstripe.org): Forums on silverstripe.org diff --git a/en/06_Project_Governance/06_Minor_release_policy.md b/en/06_Project_Governance/06_Minor_release_policy.md new file mode 100644 index 000000000..3cfc63311 --- /dev/null +++ b/en/06_Project_Governance/06_Minor_release_policy.md @@ -0,0 +1,93 @@ +--- +title: Minor Release Policy +summary: Outline the minor release lifecycle and support commitment for Silverstripe CMS +icon: code-branch +--- + +# Minor Release Policy + +This policy complements the [Silverstripe CMS Major release policy](major_release_policy) by providing guidance on when new minor releases of Silverstripe CMS are shipped. + +Note that the release cadence and pre-release time frame are indicative only. We may alter those in response to external constraints. + +Our minor release policy is more flexible because minor release upgrades are more straightforward to manage than major release upgrades. + +## Scope of the policy + +This policy applies to all [Silverstripe CMS commercially supported modules](/project_governance/supported_modules/). + +Community modules are not covered by this policy. Modules in the `silverstripe` github organisation that are not commercially supported are updated on a best effort basis. + +## Upgrading to a new minor release + +Silverstripe CMS follows [semantic versioning](https://semver.org/). Silverstripe CMS minor releases deliver new features and new APIs in a backward compatible way. + +## Minor release cadence + +Silverstripe CMS aims to ship a new minor releases every 6 months for the major release line in active development. Those minor releases are targeted for April and October each year. + +### Pre-release + +Silverstripe CMS does not usually tag alpha releases for minor releases. + +Approximately 6 weeks prior to the anticipated stable minor release, a beta minor release is published. Once a beta release is tagged, any new feature or API that didn't make it to the beta should be targeted to the follow up minor release. This allows the CMS development team to perform a regression test on the beta release with confidence that no additional regressions will be introduced before the stable release. + +Approximately 2 weeks prior to the anticipated stable minor release, a release candidate is tagged. Once a release candidate is tagged, only critical impact bug fixes can be added to the release. The release candidate is sent to an external auditor for a security review. Any security patches which will be included in the stable release are also sent to the auditor. + +### Stable release + +New minor releases of Silverstripe CMS are tagged around April and October each year. + +## Minor release support timeline + +The minor release support timeline follows similar phases to those of a major release, but are more condensed. + +### Bug and security fixes + +A Silverstripe CMS minor release line enters the *bug and security fixes* phase once it is tagged *stable*. + +A minor release in the *bug and security fixes* phase receives: +- bugfixes that do not change existing APIs +- security patches for vulnerabilities at all impact levels. + +It does **not** receive: +- new features +- new APIs. + +A minor release line stays in the *bug and security fixes* phase until a follow up minor release is tagged. + +### Security fixes only + +At the end of the *bug and security fixes* phase, a Silverstripe CMS minor release line transitions to the *security fixes only* phase. + +In the *security fixes only* phase, a Silverstripe CMS minor release line only receives patches for high impact security issues defined as having a CVSS score of 7.0 or above. + +### End-of-life + +Six months after entering the *security fixes only* phase, the minor release goes *end-of-life*. No more security patches will be shipped for that minor release. + +### The last minor release in a major release line + +Shortly before tagging a new major release, one last minor release will be tagged for the major release line in active development. + +The last minor release in a major release line will have an extended support phases in line with our [major release policy](major_release_policy). + +## Security patch windows + +Silverstripe CMS aims to deliver security patches at pre-defined intervals to make it easier to plan Silverstripe CMS project upgrades. + +When a vulnerability is [confidentially reported](/contributing/issues_and_bugs/#reporting-security-issues) to the Silverstripe CMS development team and we are confident that the vulnerability is not actively being exploited in the wild, we will wait until the next available security patch window to disclose it and release a patch. + +Security patch windows are scheduled to line up with our expected minor release. Our security patch windows are in: +- January +- April +- July +- October. + +Any security fixes that are shipped at the same time as a new minor release will also be patched and tagged on the minor release that is entering the "bug and security fixes" phase. + +## Patch releases + +Silverstripe CMS tags patch releases of individual modules whenever relevant bug fixes or other very low risk changes are merged into a supported patch release branch. + +Patches releases are not coordinated across modules and do not have a specific cadence. \ No newline at end of file diff --git a/en/06_Project_Governance/06_Supported_Modules.md b/en/06_Project_Governance/07_Supported_Modules.md similarity index 100% rename from en/06_Project_Governance/06_Supported_Modules.md rename to en/06_Project_Governance/07_Supported_Modules.md From e2fc0056fb5143d6a54edaf80114256073c9c579 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Mon, 7 Aug 2023 14:41:19 +1200 Subject: [PATCH 3/4] DOC Use correct class for keep_archived_assets config --- en/02_Developer_Guides/14_Files/04_File_Storage.md | 2 +- en/02_Developer_Guides/14_Files/05_File_Migration.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en/02_Developer_Guides/14_Files/04_File_Storage.md b/en/02_Developer_Guides/14_Files/04_File_Storage.md index 8d2f738ea..200e83801 100644 --- a/en/02_Developer_Guides/14_Files/04_File_Storage.md +++ b/en/02_Developer_Guides/14_Files/04_File_Storage.md @@ -149,7 +149,7 @@ Changes are only tracked for file metadata (e.g. the `Title` attribute). You can opt-in to retaining the file content for replaced or removed files. ```yml -SilverStripe\Assets\Flysystem\FlysystemAssetStore: +SilverStripe\Assets\File: keep_archived_assets: true ``` diff --git a/en/02_Developer_Guides/14_Files/05_File_Migration.md b/en/02_Developer_Guides/14_Files/05_File_Migration.md index 57da2bb05..19e092b77 100644 --- a/en/02_Developer_Guides/14_Files/05_File_Migration.md +++ b/en/02_Developer_Guides/14_Files/05_File_Migration.md @@ -152,7 +152,7 @@ in order to avoid bloat. If you need to retain file contents (e.g. for auditing you can opt-in to this behaviour: ```yaml -SilverStripe\Assets\Flysystem\FlysystemAssetStore: +SilverStripe\Assets\File: keep_archived_assets: true ``` From ef31438ef571564554ad9a64042bfdaecab8d06b Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Mon, 14 Aug 2023 16:27:03 +1200 Subject: [PATCH 4/4] DOC Document FieldsValidator (#319) --- .../03_Forms/00_Introduction.md | 7 +++++-- .../03_Forms/01_Validation.md | 20 ++++++++++++++++--- .../How_Tos/05_Simple_Contact_Form.md | 2 +- .../11_Integration/00_CSV_Import.md | 4 +--- .../Import_CSV_through_a_Controller.md | 4 ++-- 5 files changed, 26 insertions(+), 11 deletions(-) diff --git a/en/02_Developer_Guides/03_Forms/00_Introduction.md b/en/02_Developer_Guides/03_Forms/00_Introduction.md index df21cd9a2..84281be78 100644 --- a/en/02_Developer_Guides/03_Forms/00_Introduction.md +++ b/en/02_Developer_Guides/03_Forms/00_Introduction.md @@ -27,7 +27,7 @@ $form = new Form( $name, // name of the method that returns this form on the controller FieldList $fields, // list of FormField instances FieldList $actions, // list of FormAction instances - $required // optional use of RequiredFields object + $validator // optional use of Validator object ); ``` @@ -343,7 +343,10 @@ validating its' own data value. For more information, see the [Form Validation](validation) documentation. ```php -$validator = new SilverStripe\Forms\RequiredFields([ +use SilverStripe\Forms\Form; +use SilverStripe\Forms\RequiredFields; + +$validator = new RequiredFields([ 'Name', 'Email' ]); diff --git a/en/02_Developer_Guides/03_Forms/01_Validation.md b/en/02_Developer_Guides/03_Forms/01_Validation.md index 4abcd0f9d..41696af2a 100644 --- a/en/02_Developer_Guides/03_Forms/01_Validation.md +++ b/en/02_Developer_Guides/03_Forms/01_Validation.md @@ -6,8 +6,8 @@ icon: check-square # Form Validation -Silverstripe CMS provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validator) class and its' child class -[RequiredFields](api:SilverStripe\Forms\RequiredFields). A single `Validator` instance is set on each `Form`. Validators are implemented as an argument to +Silverstripe CMS provides server-side form validation out of the box through the [Validator](api:SilverStripe\Forms\Validator) class and its' child classes +(see [available validators](#available-validators) below). A single `Validator` instance is set on each `Form`. Validators are implemented as an argument to the [Form](api:SilverStripe\Forms\Form) constructor or through the function `setValidator`. ```php @@ -181,6 +181,20 @@ class Page_Controller extends ContentController } ``` +## Available validators + +The Silverstripe framework comes with the following built-in validators: + +- [`CompositeValidator`](api:SilverStripe\Forms\CompositeValidator) + A container for additional validators. You can implement discrete validation logic in multiple `Validator` subclasses and apply them _all_ to a + given form by putting them inside a `CompositeValidator`. The `CompositeValidator` doesn't have perform any validation by itself. +- [`FieldsValidator`](api:SilverStripe\Forms\FieldsValidator) + Simply calls [`validate()`](api:SilverStripe\Forms\FormField::validate()) on all data fields in the form, to ensure fields have valid values. +- [`RequiredFields`](api:SilverStripe\Forms\RequiredFields) + Validates that fields you declare as "required" have a value. + +There are additional validators available in community modules, and you can implement your own validators by subclassing the abstract `Validator` class. + ## Exempt validation actions In some cases you might need to disable validation for specific actions. E.g. actions which discard submitted @@ -274,7 +288,7 @@ class MyController extends Controller ### Validation in the CMS In the CMS, we're not creating the forms for editing CMS records. The `Form` instance is generated for us so we cannot -call `setValidator` easily. However, a `DataObject` can provide its' own `Validator` instance/s through the +call `setValidator` easily. However, a `DataObject` can provide its own `Validator` instance/s through the `getCMSCompositeValidator()` method. The CMS interfaces such as [LeftAndMain](api:SilverStripe\Admin\LeftAndMain), [ModelAdmin](api:SilverStripe\Admin\ModelAdmin) and [GridField](api:SilverStripe\Forms\GridField\GridField) will respect the provided `Validator`/s and handle displaying error and success responses to the user. diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md b/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md index 4d586c77e..161bd4f45 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/05_Simple_Contact_Form.md @@ -139,7 +139,7 @@ This data is used to create an email, which you then send to the address you cho The final thing we do is return a 'thank you for your feedback' message to the user. To do this we override some of the methods called in the template by returning an array. We return the HTML content we want rendered instead of the usual CMS-entered content, and we return false for Form, as we don't want the form to render. -##How to add form validation +## How to add form validation All forms have some basic validation built in – email fields will only let the user enter email addresses, number fields will only accept numbers, and so on. Sometimes you need more complicated validation, so you can define your own validation by extending the Validator class. diff --git a/en/02_Developer_Guides/11_Integration/00_CSV_Import.md b/en/02_Developer_Guides/11_Integration/00_CSV_Import.md index 8f5a1bd99..21401d8d8 100644 --- a/en/02_Developer_Guides/11_Integration/00_CSV_Import.md +++ b/en/02_Developer_Guides/11_Integration/00_CSV_Import.md @@ -88,7 +88,6 @@ use SilverStripe\Forms\Form; use SilverStripe\Forms\FieldList; use SilverStripe\Forms\FileField; use SilverStripe\Forms\FormAction; -use SilverStripe\Forms\RequiredFields; use SilverStripe\Dev\CsvBulkLoader; use SilverStripe\Control\Controller; @@ -114,8 +113,7 @@ class MyController extends Controller ), new FieldList( new FormAction('doUpload', 'Upload') - ), - new RequiredFields() + ) ); return $form; } diff --git a/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md b/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md index 10b5a355b..1400d5f69 100644 --- a/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md +++ b/en/02_Developer_Guides/11_Integration/How_Tos/Import_CSV_through_a_Controller.md @@ -16,7 +16,7 @@ use SilverStripe\Forms\Form; use SilverStripe\Forms\FieldList; use SilverStripe\Forms\FileField; use SilverStripe\Forms\FormAction; -use SilverStripe\Forms\RequiredFields; +use SilverStripe\Forms\FieldsValidator; use SilverStripe\Dev\CsvBulkLoader; use SilverStripe\Control\Controller; @@ -45,7 +45,7 @@ class MyController extends Controller new FieldList( new FormAction('doUpload', 'Upload') ), - new RequiredFields() + new FieldsValidator() ); return $form; }