-
Notifications
You must be signed in to change notification settings - Fork 67
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
DOC Update references from CMS 5 #644
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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) | ||
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unrelated but since blog isn't commercially supported I'm removing the reference. |
||
``` | ||
|
||
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 | ||
|
||
|
@@ -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. | ||
|
||
|
@@ -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": [ | ||
|
@@ -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 | ||
|
@@ -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. | ||
|
@@ -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 | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
``` | ||
Comment on lines
-37
to
43
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unrelated but since blog isn't commercially supported I'm removing the reference. |
||
|
||
This will fetch the latest compatible stable version of the module. | ||
|
@@ -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" | ||
} | ||
} | ||
``` | ||
|
@@ -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. | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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*. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use |
||
- 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. | ||
|
||
|
@@ -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 | ||
Comment on lines
-31
to
+32
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
- 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 | ||
); | ||
|
@@ -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. | ||
|
||
|
@@ -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 | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I was going to replace with a more generic examples but honestly I don't think it's needed. |
||
|
||
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: | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note I intentionally kept these, since the bit above it says
That implies the table is meant to include the previous major's PHP versions