Skip to content

Commit

Permalink
DOC Update references from CMS 5
Browse files Browse the repository at this point in the history
Also remove CMS 5 changelogs
  • Loading branch information
GuySartorelli committed Dec 3, 2024
1 parent 5e4f836 commit 3c116d4
Show file tree
Hide file tree
Showing 32 changed files with 139 additions and 21,528 deletions.
2 changes: 1 addition & 1 deletion en/00_Getting_Started/00_Server_Requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ table may be of use:
| 5.2 + | 8.1 - 8.3 |
| 5.0 - 5.1 | 8.1 - 8.2 |

From Silverstripe CMS 5 onwards, the [Silverstripe CMS major release policy](/project_governance/major_release_policy#php-support-commitments) guides which PHP versions are supported by which Silverstripe CMS release.
The [Silverstripe CMS major release policy](/project_governance/major_release_policy#php-support-commitments) guides which PHP versions are supported by which Silverstripe CMS release.

## CMS browser requirements

Expand Down
48 changes: 24 additions & 24 deletions en/00_Getting_Started/02_Composer.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,10 @@ This will get all the code that you need. As long as your web server and databas
visit the site in your web browser and the installation process will be completed.

You can also specify a constraint to download explicit versions or set boundary conditions for what versions Composer is allowed to install.
For example, this will download the latest patch of the `4.13` release:
For example, this will download the latest patch of the `6.0` release:

```bash
composer create-project silverstripe/installer ./my-project ^4.13
composer create-project silverstripe/installer ./my-project ^6.0
```

Learn more about Composer constraints in [the official composer documentation](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints)
Expand All @@ -74,21 +74,21 @@ You can find thousands of Silverstripe CMS modules on [Packagist](https://packag
Installing a module can be done with [the require command](https://getcomposer.org/doc/03-cli.md#require-r):

```bash
composer require silverstripe/blog
composer require dnadesign/silverstripe-elemental
```

This will install the `silverstripe/blog` module in the latest compatible version. If you know the specific version you
want to install already (such as `^2`), you can add it after the package name as
This will install the `dnadesign/silverstripe-elemental` module in the latest compatible version. If you know the specific version you
want to install already (such as `^6`), you can add it after the package name as
a [version constraint](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints):

```bash
composer require silverstripe/blog ^2
composer require dnadesign/silverstripe-elemental ^6
```

> [!WARNING]
> **Version constraints:** `master` or `main` is not a legal version string - it's a branch name. These are different things. The
> version string that would get you the branch is `dev-main`. The version string that would get you a numeric branch is
> a little different. The version string for the `5` branch is `5.x-dev`.
> a little different. The version string for the `6` branch is `6.x-dev`.
## Updating dependencies

Expand Down Expand Up @@ -150,12 +150,12 @@ things in order to be able to do this:
The first two steps are done as part of the initial create project using additional arguments.

```bash
composer create-project --keep-vcs silverstripe/installer ./my-project 5.x-dev --prefer-source
composer create-project --keep-vcs silverstripe/installer ./my-project 6.x-dev --prefer-source
```

The process will take a bit longer, since all modules are checked out as full git repositories which you can work on.
The command checks out from the 5.x release line. If you are providing a patch to fix a bug, replace `5.x-dev` with the
latest minor branch instead, e.g. `5.1.x-dev` if the latest minor release was for CMS 5.1.
The command checks out from the 6.x release line. If you are providing a patch to fix a bug, replace `6.x-dev` with the
latest minor branch instead, e.g. `6.1.x-dev` if the latest minor release was for CMS 6.1.

The `--keep-vcs` flag will make sure you have access to the git history of the installer and the requirements.

Expand Down Expand Up @@ -184,14 +184,14 @@ file. It will appear in your project root, and by default, it will look somethin
"description": "The SilverStripe Framework Installer",
"require": {
"php": "^8.3",
"silverstripe/recipe-plugin": "^2",
"silverstripe/vendor-plugin": "^2",
"silverstripe/recipe-cms": "~5.0.0@stable",
"silverstripe-themes/simple": "~3.2.0",
"silverstripe/login-forms": "~5.0.0@stable"
"silverstripe/recipe-plugin": "~2.0.1@stable",
"silverstripe/vendor-plugin": "~2.0.3@stable",
"silverstripe/recipe-cms": "~6.0.0@stable",
"silverstripe-themes/simple": "~3.2.0@stable",
"silverstripe/login-forms": "~6.0.0@stable"
},
"require-dev": {
"phpunit/phpunit": "^9.5"
"phpunit/phpunit": "^11.3"
},
"extra": {
"project-files-installed": [
Expand Down Expand Up @@ -249,13 +249,13 @@ This is a two step process. First you get Composer to start a project based on t
silverstripe/installer

```bash
composer create-project silverstripe/installer ./my-project 5.x-dev
composer create-project silverstripe/installer ./my-project 6.x-dev
```

Or for the latest development version in the 5.0.x minor release (i.e. if you're developing a bug fix)
Or for the latest development version in the 6.0.x minor release (i.e. if you're developing a bug fix)

```bash
composer create-project silverstripe/installer ./my-project 5.0.x-dev
composer create-project silverstripe/installer ./my-project 6.0.x-dev
```

### Working with project forks and unreleased modules
Expand Down Expand Up @@ -325,12 +325,12 @@ the ["Repositories" chapter of the Composer documentation](https://getcomposer.o
#### Forks and branch names

For simplicity, you should keep using the same pattern of branch names as the main repositories does. If your version is a
fork of 5.0, then call the branch `5.0`, not `5.0-myproj` or `myproj`. Otherwise, the dependency resolution gets
fork of 6.0, then call the branch `6.0`, not `6.0-myproj` or `myproj`. Otherwise, the dependency resolution gets
confused.

Sometimes, however, this isn't feasible. For example, you might have a number of project forks stored in a single
repository, such as your personal GitHub fork of a project. Or you might be testing/developing a feature branch. Or it
might just be confusing to other team members to call the branch of your modified version `5.0`.
might just be confusing to other team members to call the branch of your modified version `6.0`.

In this case, you need to use Composer's aliasing feature to specify how you want the project branch to be treated, when
it comes to dependency resolution.
Expand All @@ -341,15 +341,15 @@ Open `composer.json`, and find the module's `require`. Then put `as (core versio
{
"require": {
"php": "^8.3",
"silverstripe/recipe-cms": "~5.0.0@stable",
"silverstripe/framework": "dev-myproj as 5.0.0",
"silverstripe/recipe-cms": "~6.0.0@stable",
"silverstripe/framework": "dev-myproj as 6.0.0",
"silverstripe-themes/simple": "~3.2.0"
}
}
```

What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies
that `5.0.0` would meet. So, if another module has `"silverstripe/framework": "^5.0.0"` in its dependency list, it
that `6.0.0` would meet. So, if another module has `"silverstripe/framework": "^6.0.0"` in its dependency list, it
won't get a conflict.

Both the version and the alias are specified as Composer versions, not branch names. For the relationship between
Expand Down
6 changes: 3 additions & 3 deletions en/02_Developer_Guides/01_Templates/02_Common_Variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,18 +115,18 @@ on a per-page basis.
> [!WARNING]
> If you don’t want to include the title tag use `$MetaTags(false)`.
By default `$MetaTags` renders (assuming 5.1.0 is the current version of `silverstripe/framework`):
By default `$MetaTags` renders (assuming 6.0.0 is the current version of `silverstripe/framework`):

```html
<title>Title of the Page</title>
<meta name="generator" content="Silverstripe CMS 5.1">
<meta name="generator" content="Silverstripe CMS 6.0">
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
```

`$MetaTags(false)` will render

```html
<meta name="generator" content="Silverstripe CMS 5.1">
<meta name="generator" content="Silverstripe CMS 6.0">
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
```

Expand Down
16 changes: 8 additions & 8 deletions en/02_Developer_Guides/05_Extending/00_Modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@ enables you to install modules from specific versions, checking for compatibilit
to track development branches of them. To install modules using this method, you will first need to setup Silverstripe CMS
with [Composer](../../getting_started/composer).

Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "blog" module has the
identifier `silverstripe/blog` as it is published by *Silverstripe*. To install, use the following command executed in
Each module has a unique identifier, consisting of a vendor prefix and name. For example, the "linkfield" module has the
identifier `silverstripe/linkfield` as it is published by *Silverstripe*. To install, use the following command executed in
the project root folder:

```bash
composer require silverstripe/blog
composer require silverstripe/linkfield
```

This will fetch the latest compatible stable version of the module.
Expand Down Expand Up @@ -76,17 +76,17 @@ You can either edit the file directly in GitHub, or you can clone the repository
using this directory to update the `composer.json` file. Once that's updated in the repository, you'll use Composer to include your module in
a Silverstripe CMS project and do your development from there.

Here is an example for a module that builds on the functionality provided by the `silverstripe/blog` module, so it has that module as a dependency:
Here is an example for a module that builds on the functionality provided by the `silverstripe/linkfield` module, so it has that module as a dependency:

```json
{
"name": "my_vendor/module_name",
"description": "Short module description",
"type": "silverstripe-vendormodule",
"require": {
"silverstripe/framework": "^5.0",
"silverstripe/cms": "^5.0",
"silverstripe/blog": "^5.0"
"silverstripe/framework": "^6.0",
"silverstripe/cms": "^6.0",
"silverstripe/linkfield": "^5.0"
}
}
```
Expand Down Expand Up @@ -170,7 +170,7 @@ which the Silverstripe CMS project applies to the modules it creates and maintai
- `tests/` (for `*Test.php` test files), and;
- `_config/` (for `.yml` config files)
- The module is a Composer package.
- All Composer dependencies are bound to a single major release (e.g. `^5.0` not `>=5` or `*`) unless there are obvious reasons not to for some specific dependency.
- All Composer dependencies are bound to a single major release (e.g. `^6.0` not `>=6`) unless there are obvious reasons not to for some specific dependency.
- There is a level of test coverage.
- Uses strong typing where appropriate.
- A clear [public API](/project_governance/public_api/) documented in the docblock tags.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ For more information about what your `composer.json` file should include, consul
"issues": "https://github.com/my-vendor/my-module/issues"
},
"require": {
"silverstripe/cms": "^5",
"silverstripe/framework": "^5"
"silverstripe/cms": "^6",
"silverstripe/framework": "^6"
},
"autoload": {
"psr-4": {
Expand Down Expand Up @@ -77,19 +77,19 @@ By using Composer, this is made easy for developers by allowing them to specify
version of your module should be a separate branch in your version control and each branch should have a `composer.json`
file explicitly defining what versions of Silverstripe CMS you support.

Say you have a module which supports Silverstripe CMS 5.0. A new release of this module takes advantage of new features
in Silverstripe CMS 5.1. In this case, you would create a new branch for the 5.0 compatible code base of your module. This
Say you have a module which supports Silverstripe CMS 6.0. A new release of this module takes advantage of new features
in Silverstripe CMS 6.1. In this case, you would create a new branch for the 6.0 compatible code base of your module. This
allows you to continue fixing bugs on this older release branch.

Other branches should be created on your module as needed if they're required to support specific Silverstripe CMS releases.

You can have an overlap in supported versions, e.g two branches in your module both support Silverstripe CMS 5.0. In this
You can have an overlap in supported versions, e.g two branches in your module both support Silverstripe CMS 6.0. In this
case, you should explain the differences in your `README.md` file.

Here's some common values for your `require` section
(see [getcomposer.org](https://getcomposer.org/doc/01-basic-usage.md#package-versions) for details):

- `5.0.*`: Version `5.0`, including `5.0.1`, `5.0.2` etc, excluding `5.1`
- `~5.0`: Version `5.0` or higher, including `5.0.1` and `5.1` etc, excluding `6.0`
- `~5.0,<5.2`: Version `5.0` or higher, up until `5.2`, which is excluded
- `~5.0,>5.0.4`: Version `5.0` or higher, starting with `5.0.4`
- `6.0.*`: Version `6.0`, including `6.0.1`, `6.0.2` etc, excluding `6.1`
- `~6.0`: Version `6.0` or higher, including `6.0.1` and `6.1` etc, excluding `7.0`
- `~6.0,<6.2`: Version `6.0` or higher, up until `6.2`, which is excluded
- `~6.0,>6.0.4`: Version `6.0` or higher, starting with `6.0.4`
26 changes: 13 additions & 13 deletions en/02_Developer_Guides/20_Deprecations/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ going to be removed and how they need to update their code.
- Add a `@deprecated` item to the docblock tag, with the version when the code was deprecated and a message indicating what to use instead.
- Update the deprecated code to throw a [Deprecation::notice()](api:SilverStripe\Dev\Deprecation::notice()) warning.
- Both the docblock and error message should contain the **version** where the functionality is deprecated from.
So, if you're committing the change to a *4.12* minor release, the version will be *4.12.0*.
So, if you're committing the change to a *1.2* minor release, the version will be *1.2.0*.
- Make sure that the old deprecated method works by calling the new function where possible - avoid duplicated code.
- Deprecated APIs can be removed only after developers have had sufficient time to react to the changes. Hence, deprecated APIs should be removed in major releases only. Between major releases, leave the code in place with a deprecation warning.

Expand All @@ -28,29 +28,29 @@ going to be removed and how they need to update their code.
When deprecating a method:

- Add the following docblock `@deprecated 1.2.3 Use anotherMethod() instead`
- `Deprecation::notice('1.2.3', 'Use anotherMethod() instead');` to the top of the method
- Add the following docblock `@deprecated 1.2.0 Use anotherMethod() instead`
- `Deprecation::notice('1.2.0', 'Use anotherMethod() instead');` to the top of the method
- Wrap `Deprecation::notice()` with `Deprecation::withSuppressedNotice()` if there's no replacement for that deprecated method and it's not feasible to wrap all calls to the method

When deprecating a class:

- Add the following docblock `@deprecated 1.2.3 Use AnotherClass instead`
- Add `Deprecation::notice('1.2.3', 'Use AnotherClass instead', Deprecation::SCOPE_CLASS);` to the top of `__construct()`
- Add the following docblock `@deprecated 1.2.0 Use AnotherClass instead`
- Add `Deprecation::notice('1.2.0', 'Use AnotherClass instead', Deprecation::SCOPE_CLASS);` to the top of `__construct()`
- Wrap `Deprecation::notice()` with `Deprecation::withSuppressedNotice()` if there's no replacement for that deprecated class and it's not feasible to wrap all instantiations of the class

```php
namespace App;

/**
* @deprecated 4.12.0 Will be removed without equivalent functionality
* @deprecated 1.2.0 Will be removed without equivalent functionality
*/
class MyDeprecatedClass extends AnotherClass
{
public function __construct()
{
Deprecation::withSuppressedNotice(function () {
Deprecation::notice(
'4.12.0',
'1.2.0',
'Will be removed without equivalent functionality',
Deprecation::SCOPE_CLASS
);
Expand All @@ -62,11 +62,11 @@ When deprecating a class:

When deprecating config:

- Add the following docblock `@deprecated 1.2.3 Use different_config instead`
- Add the following docblock `@deprecated 1.2.0 Use different_config instead`

When deprecating some behaviour, combination of configuration values, parameters, etc:

- Add `Deprecation::notice('1.2.3', 'Using x with y is deprecated. Do [other thing] instead', Deprecation::SCOPE_GLOBAL);`
- Add `Deprecation::notice('1.2.0', 'Using x with y is deprecated. Do [other thing] instead', Deprecation::SCOPE_GLOBAL);`
- It may not be immediately clear where this type of deprecation warning should go. In that case, add it to the `HTTPApplication::warnAboutDeprecatedSetups()` method.
- It may be appropriate to link to some documentation in the message for this type of deprecation warning.

Expand Down Expand Up @@ -123,18 +123,18 @@ class Director

/**
* Returns true if your are in development mode
* @deprecated 4.12.0 Use SilverStripe\Core\Env::is_dev() instead.
* @deprecated 1.2.0 Use SilverStripe\Core\Env::is_dev() instead.
*/
public function isDev()
{
Deprecation::notice('4.12.0', 'Use SilverStripe\Core\Env::is_dev() instead');
Deprecation::notice('1.2.0', 'Use SilverStripe\Core\Env::is_dev() instead');
return Env::is_dev();
}
}
```

This change could be committed to a minor release like *4.12.0*, and remains deprecated in all subsequent minor releases
(e.g. *4.13.0*), until a new major release (e.g. *5.0.0*), at which point it gets removed from the codebase.
This change could be committed to a minor release like *1.2.0*, and remains deprecated in all subsequent minor releases
(e.g. *1.3.0*), until a new major release (e.g. *2.0.0*), at which point it gets removed from the codebase.

## Enabling deprecation warnings

Expand Down
6 changes: 3 additions & 3 deletions en/06_Upgrading/01_Keeping_projects_up_to_date.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,13 @@ Assuming your project is using one of the [supported recipes](/getting_started/r

To upgrade your code, open the root `composer.json` file. Find the lines that reference the recipes, like `silverstripe/recipe-cms` and change the referenced versions to what has been reference in the changelog (as well as any other modules that have a new version).

For example, assuming that you are currently on version `~5.0.0@stable`, if you wish to upgrade to 5.1.0 you will need to modify your `composer.json` file to explicitly specify the new release branch, here `~5.1.0`:
For example, assuming that you are currently on version `~6.0.0@stable`, if you wish to upgrade to 6.1.0 you will need to modify your `composer.json` file to explicitly specify the new release branch, here `~6.1.0`:

```json
{
...
"require": {
"silverstripe/recipe-cms": "~5.1.0"
"silverstripe/recipe-cms": "~6.1.0"
},
...
}
Expand All @@ -45,7 +45,7 @@ You now need to pull in new dependencies and commit the lock file:

```bash
composer update
git commit composer.* -m "Upgrade to recipe 5.1.0"
git commit composer.* -m "Upgrade to recipe 6.1.0"
```

Push this commit to your remote repository, and continue with your deployment workflow.
Expand Down
2 changes: 1 addition & 1 deletion en/06_Upgrading/07_Deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Deprecation::enable();
Once you have resolved all of the deprecation warnings you can, it is recommended to turn off deprecation warnings again.

Not all API that gets deprecated will have an equivalent replacement API in that same major version; some of the API is only available from the next major release. A good example of this is the upgrade for what powered the `SilverStripe\Control\Email\Email` class from `swiftmailer` in CMS 4 to `symfony/mailer` in CMS 5. In these cases, you'll need to upgrade to the new major version before you can access the replacement API.
Not all API that gets deprecated will have an equivalent replacement API in that same major version; some of the API is only available from the next major release. In these cases, you'll need to upgrade to the new major version before you can access the replacement API.

Some code that has been deprecated with no immediate replacement will not emit deprecation notices by default. If you wish to also see notices for deprecated code with no immediate replacement, add the following line to you project's `app/_config.php` file:

Expand Down
Loading

0 comments on commit 3c116d4

Please sign in to comment.