mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
DOCS Add 4.0 upgrade guide, update "composer" and "modules" to include 4.x recommended practices
This commit is contained in:
Robbie Averill
parent
b40904ffa7
commit
394af0615f
@ -15,7 +15,9 @@ Next, [install composer](https://getcomposer.org/download/). For our documentati
|
||||
|
||||
You can then run Composer commands by calling `composer`. For example:
|
||||
|
||||
composer help
|
||||
```
|
||||
composer help
|
||||
```
|
||||
|
||||
<div class="hint" markdown="1">
|
||||
It is also possible to keep `composer.phar` out of your path, for example, to put it in your project root. Every command would then start with `php composer.phar` instead of `composer`. This is handy if need to keep your installation isolated from the rest of your computer's set-up, but we recommend putting composer into the path for most people.
|
||||
@ -25,7 +27,9 @@ It is also possible to keep `composer.phar` out of your path, for example, to pu
|
||||
|
||||
If you already have composer installed you can update it by running:
|
||||
|
||||
sudo composer self-update
|
||||
```
|
||||
sudo composer self-update
|
||||
```
|
||||
|
||||
Composer updates regularly, so you should run this command fairly often. These instructions assume you are running the latest version.
|
||||
|
||||
@ -36,16 +40,20 @@ For those that use WAMP as a development environment, [detailed information is a
|
||||
|
||||
Composer can create a new site for you, using the installer as a template (by default composer will download the latest stable version):
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder
|
||||
```
|
||||
|
||||
`./my/website/folder` should be the root directory where your site will live.
|
||||
For example, on OS X, you might use a subdirectory of `~/Sites`.
|
||||
As long as your web server is up and running, this will get all the code that you need.
|
||||
Now visit the site in your web browser, and the installation process will be completed.
|
||||
|
||||
You can also specify a version to download that version explicitly, i.e. this will download the older `3.0.3` release:
|
||||
You can also specify a version to download that version explicitly, i.e. this will download the older `3.5.0` release:
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.0.3
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.5.0
|
||||
```
|
||||
|
||||
When `create-project` is used with a release version like above,
|
||||
it will try to get the code from archives instead of creating
|
||||
@ -56,27 +64,34 @@ see [Using development versions](#using-development-versions).
|
||||
|
||||
Composer isn't only used to download SilverStripe CMS, it can also be used to manage all SilverStripe modules. Installing a module can be done with the following command:
|
||||
|
||||
composer require "silverstripe/forum:*"
|
||||
```
|
||||
composer require "silverstripe/forum:*"
|
||||
```
|
||||
|
||||
This will install the forum module in the latest compatible version. You can also omit the `:*` if you simply want the latest compatible version of the module.
|
||||
|
||||
This will install the forum module in the latest compatible version.
|
||||
By default, Composer updates other existing modules (like `framework` and `cms`),
|
||||
and installs "dev" dependencies like PHPUnit. In case you don't need those dependencies,
|
||||
use the following command instead:
|
||||
|
||||
composer require --no-update "silverstripe/forum:*"
|
||||
composer update --no-dev
|
||||
```
|
||||
composer require --no-update "silverstripe/forum:*"
|
||||
composer update --no-dev
|
||||
```
|
||||
|
||||
The `require` command has two parts. First is `silverstripe/forum`. This is the name of the package.
|
||||
You can find other packages with the following command:
|
||||
|
||||
composer search silverstripe
|
||||
```
|
||||
composer search silverstripe
|
||||
```
|
||||
|
||||
This will return a list of package names of the forum `vendor/package`. If you prefer, you can search for packages on [packagist.org](https://packagist.org/search/?q=silverstripe).
|
||||
|
||||
The second part after the colon, `*`, is a version string. `*` is a good default: it will give you the latest version that works with the other modules you have installed. Alternatively, you can specificy a specific version, or a constraint such as `>=3.0`. For more information, read the [Composer documentation](http://getcomposer.org/doc/01-basic-usage.md#the-require-key).
|
||||
The second part after the colon, `*`, is a version string. `*` is a good default: it will give you the latest version that works with the other modules you have installed. Alternatively you can specify a specific version, or a constraint such as `^4.0`. For more information, read the [Composer documentation](http://getcomposer.org/doc/01-basic-usage.md#the-require-key).
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
`master` 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-master`. The version string that would get you a numeric branch is a little different. The version string for the `3.0` branch is `3.0.x-dev`.
|
||||
`master` 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-master`. The version string that would get you a numeric branch is a little different. The version string for the `3` branch is `3.x-dev`.
|
||||
</div>
|
||||
|
||||
## Updating dependencies
|
||||
@ -85,17 +100,19 @@ Except for the control code of the Voyager space probe, every piece of code in t
|
||||
|
||||
To get the latest updates of the modules in your project, run this command:
|
||||
|
||||
composer update --no-dev
|
||||
```
|
||||
composer update --no-dev
|
||||
```
|
||||
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific commits of each of those.
|
||||
Updates to the required modules will be installed, and the `composer.lock` file will get updated with the specific commits and version constraints for each of them.
|
||||
|
||||
## Deploying projects with Composer
|
||||
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. However, this is risky. In particular, if you were referencing development dependencies and a change was made between your testing and your depoyment to production, you would end up deploying untested code. Not cool!
|
||||
When deploying projects with composer, you could just push the code and run `composer update`. This, however, is risky. In particular, if you were referencing development dependencies and a change was made between your testing and your deployment to production, you would end up deploying untested code. Not cool!
|
||||
|
||||
The `composer.lock` file helps with this. It references the specific commits that have been checked out, rather than the version string. You can run `composer install` to install dependencies from this rather than `composer.json`.
|
||||
|
||||
So, your deployment process, as it relates to Composer, should be as follows:
|
||||
So your deployment process, as it relates to Composer, should be as follows:
|
||||
|
||||
* Run `composer update` on your development version before you start whatever testing you have planned. Perform all the necessary testing.
|
||||
* Check `composer.lock` into your repository.
|
||||
@ -110,18 +127,20 @@ Since SilverStripe modules are installed into their own folder, you have to mana
|
||||
|
||||
Here is the default SilverStripe [.gitignore](http://git-scm.com/docs/gitignore) with the forum module ignored
|
||||
|
||||
assets/*
|
||||
_ss_environment.php
|
||||
tools/phing-metadata
|
||||
silverstripe-cache
|
||||
.buildpath
|
||||
.project
|
||||
.settings
|
||||
.idea
|
||||
.DS_Store
|
||||
vendor/
|
||||
# Don't include the forum module, as this will be installed with composer
|
||||
forum
|
||||
```
|
||||
assets/*
|
||||
_ss_environment.php
|
||||
tools/phing-metadata
|
||||
silverstripe-cache
|
||||
.buildpath
|
||||
.project
|
||||
.settings
|
||||
.idea
|
||||
.DS_Store
|
||||
vendor/
|
||||
# Don't include the forum module, as this will be installed with composer
|
||||
forum
|
||||
```
|
||||
|
||||
In large projects it can get difficult to manage your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it contains all composer managed modules and themes.
|
||||
|
||||
@ -132,13 +151,17 @@ This package will maintain your [.gitignore](http://git-scm.com/docs/gitignore)
|
||||
|
||||
Include the package in your project by running this command
|
||||
|
||||
composer require gdmedia/ss-auto-git-ignore --dev
|
||||
```
|
||||
composer require gdmedia/ss-auto-git-ignore --dev
|
||||
```
|
||||
|
||||
Edit your composer.json and insert
|
||||
Edit your `composer.json` and insert:
|
||||
|
||||
"scripts": {
|
||||
```json
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This will instruct composer to run SSAutoGitIgnore after every update. SSAutoGitIgnore will then ensure composer managed models and themes are correctly added to your [.gitignore](http://git-scm.com/docs/gitignore).
|
||||
For more information about SSAutoGitIgnore, see the [SSAutoGitIgnore home page](https://github.com/guru-digital/SSAutoGitIgnore/).
|
||||
@ -146,13 +169,14 @@ For more information about post-updated-cmd and scripts, read the ["Scripts" cha
|
||||
|
||||
Full example of composer.json with the SSAutoGitIgnore installed and enabled
|
||||
|
||||
{
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.*",
|
||||
"silverstripe/framework": "3.0.*",
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "^4.0",
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
"require-dev": {
|
||||
@ -163,8 +187,10 @@ Full example of composer.json with the SSAutoGitIgnore installed and enabled
|
||||
"scripts": {
|
||||
"post-update-cmd": "GDM\\SSAutoGitIgnore\\UpdateScript::Go"
|
||||
},
|
||||
"minimum-stability": "dev"
|
||||
}
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
||||
```
|
||||
|
||||
# Dev Environments for Contributing Code {#contributing}
|
||||
|
||||
@ -177,11 +203,12 @@ You have to tell composer three 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.
|
||||
|
||||
```
|
||||
composer create-project --keep-vcs --dev silverstripe/installer ./my/website/folder 4.0.x-dev
|
||||
```
|
||||
|
||||
composer create-project --keep-vcs --dev silverstripe/installer ./my/website/folder 3.0.x-dev
|
||||
|
||||
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 3.0 release line. To check out from master instead,
|
||||
replace `3.0.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
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 4.0 release line. To check out from master instead,
|
||||
replace `4.0.x-dev` with `dev-master` (more info on [composer version naming](http://getcomposer.org/doc/02-libraries.md#specifying-the-version)).
|
||||
|
||||
The `--keep-vcs` flag will make sure you have access to the git history of the installer and the requirements
|
||||
|
||||
@ -206,27 +233,32 @@ create forks and send pull requests.
|
||||
|
||||
To remove dependencies, or if you prefer seeing all your dependencies in a text file, you can edit the `composer.json` file. It will appear in your project root, and by default, it will look something like this:
|
||||
|
||||
{
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.*",
|
||||
"silverstripe/framework": "3.0.*",
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "^4.0",
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
"require-dev": {
|
||||
"silverstripe/compass": "*",
|
||||
"silverstripe/docsviewer": "*"
|
||||
},
|
||||
"minimum-stability": "dev"
|
||||
}
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
||||
```
|
||||
|
||||
To add modules, you should add more entries into the `"require"` section. For example, we might add the blog and forum modules. Be careful with the commas at the end of the lines!
|
||||
|
||||
Save your file, and then run the following command to refresh the installed packages:
|
||||
|
||||
composer update
|
||||
```
|
||||
composer update
|
||||
```
|
||||
|
||||
## Using development versions
|
||||
|
||||
@ -239,15 +271,19 @@ is this required if you want to contribute back to the SilverStripe project, it
|
||||
This is a two step process. First you get composer to start a project based on
|
||||
the latest unstable silverstripe/installer
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder master-dev
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder dev-master
|
||||
```
|
||||
|
||||
Or for the latest development version in the 3.0.x series
|
||||
|
||||
composer create-project silverstripe/installer ./my/website/folder 3.0.x-dev
|
||||
```
|
||||
composer create-project silverstripe/installer ./my/website/folder 4.0.x-dev
|
||||
```
|
||||
|
||||
## Working with project forks and unreleased modules
|
||||
|
||||
By default, Composer will install modules listed on the packagist site. There a few reasons that you might not
|
||||
By default, Composer will install modules listed on the Packagist site. There are a few reasons that you might not
|
||||
want to do this. For example:
|
||||
|
||||
* You may have your own fork of a module, either specific to a project, or because you are working on a pull request
|
||||
@ -261,7 +297,8 @@ This is how you do it:
|
||||
|
||||
* **List all your fork repositories in your project's composer.json files.** You do this in a `repositories` section. Set the `type` to `vcs`, and `url` to the URL of the repository. The result will look something like this:
|
||||
|
||||
{
|
||||
```json
|
||||
{
|
||||
"name": "silverstripe/installer",
|
||||
"description": "The SilverStripe Framework Installer",
|
||||
|
||||
@ -270,45 +307,49 @@ This is how you do it:
|
||||
"type": "vcs",
|
||||
"url": "git@github.com:sminnee/silverstripe-cms.git"
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
* **Install the module as you would normally.** Use the regular composer function - there are no special flags to use a fork. Your fork will be used in place of the package version.
|
||||
|
||||
composer require silverstripe/cms
|
||||
```
|
||||
composer require silverstripe/cms
|
||||
```
|
||||
|
||||
Composer will scan all of the repositories you list, collect meta-data about the packages within them, and use them in favour of the packages listed on packagist. To switch back to using the mainline version of the package, just remove the `repositories` section from `composer.json` and run `composer update`.
|
||||
|
||||
Now add an "upstream" remote to the original repository location so you can rebase or merge your fork as required.
|
||||
|
||||
cd cms
|
||||
git remote add -f upstream git://github.com/silverstripe/silverstripe-cms.git
|
||||
```
|
||||
cd cms
|
||||
git remote add -f upstream git://github.com/silverstripe/silverstripe-cms.git
|
||||
```
|
||||
|
||||
For more information, read the ["Repositories" chapter of the Composer documentation](http://getcomposer.org/doc/05-repositories.md).
|
||||
|
||||
### Forks and branch names
|
||||
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a fork of 3.0, then call the branch `3.0`, not `3.0-myproj` or `myproj`. Otherwise, the dependency resolution gets confused.
|
||||
Generally, you should keep using the same pattern of branch names as the main repositories does. If your version is a fork of 4.0, then call the branch `4.0`, not `4.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 `3.0`.
|
||||
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 `4.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.
|
||||
|
||||
Open `composer.json`, and find the module's `require`. Then put `as (core version name)` on the end.
|
||||
|
||||
{
|
||||
...
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"php": ">=5.3.2",
|
||||
"silverstripe/cms": "3.0.2.1",
|
||||
"silverstripe/framework": "dev-myproj as 3.0.x-dev",
|
||||
"php": ">=5.5.0",
|
||||
"silverstripe/cms": "3.5.1.2",
|
||||
"silverstripe/framework": "dev-myproj as 4.0.x-dev",
|
||||
"silverstripe-themes/simple": "*"
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies that 3.0.x-dev would meet. So, if another module has `"silverstripe/framework": ">=3.0.0"` in its dependency list, it won't get a conflict.
|
||||
What this means is that when the `myproj` branch is checked out into a project, this will satisfy any dependencies that `4.0.x-dev` would meet. So, if another module has `"silverstripe/framework": "^4.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 branch/tag names and Composer versions, read [the relevant Composer documentation](http://getcomposer.org/doc/02-libraries.md#specifying-the-version).
|
||||
|
||||
|
||||
@ -10,16 +10,18 @@ A module is a collection of classes, templates, and other resources that is load
|
||||
the `framework`, `cms` or `mysite` folders. The only thing that identifies a folder as a SilverStripe module is the
|
||||
existence of a `_config` directory or `_config.php` at the top level of the directory.
|
||||
|
||||
mysite/
|
||||
|
|
||||
+-- _config/
|
||||
+-- code/
|
||||
+-- ..
|
||||
|
|
||||
my_custom_module/
|
||||
|
|
||||
+-- _config/
|
||||
+-- ...
|
||||
```
|
||||
mysite/
|
||||
|
|
||||
+-- _config/
|
||||
+-- src/
|
||||
+-- ..
|
||||
|
|
||||
my_custom_module/
|
||||
|
|
||||
+-- _config/
|
||||
+-- ...
|
||||
```
|
||||
|
||||
SilverStripe will automatically include any PHP classes and templates from within your module when you next flush your
|
||||
cache.
|
||||
@ -38,7 +40,7 @@ are also abstracted into modules allowing developers the freedom to choose what
|
||||
|
||||
* [Official module list on silverstripe.org](http://addons.silverstripe.org/)
|
||||
* [Packagist.org "silverstripe" tag](https://packagist.org/search/?tags=silverstripe)
|
||||
* [Github.com "silverstripe" search](https://github.com/search?q=silverstripe&ref=commandbar)
|
||||
* [GitHub.com "silverstripe" search](https://github.com/search?q=silverstripe)
|
||||
|
||||
## Installation
|
||||
|
||||
@ -50,7 +52,7 @@ The root directory is the one containing the *framework* and *mysite* subdirecto
|
||||
</div>
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
After you add or remove modules make sure you rebuild the database by going to http://yoursite.com/dev/build?flush=1
|
||||
After you add or remove modules, make sure you rebuild the database, class and configuration manifests by going to http://yoursite.com/dev/build?flush=1
|
||||
</div>
|
||||
|
||||
### From Composer
|
||||
@ -64,17 +66,19 @@ Each module has a unique identifier, consisting of a vendor prefix and name. For
|
||||
identifier `silverstripe/blog` as it is published by *silverstripe*. To install, use the following command executed in
|
||||
the root folder:
|
||||
|
||||
:::bash
|
||||
composer require "silverstripe/blog" "*@stable"
|
||||
```bash
|
||||
composer require silverstripe/blog *@stable
|
||||
```
|
||||
|
||||
This will fetch the latest compatible stable version of the module. To install a specific version of the module give the
|
||||
tag name.
|
||||
|
||||
:::bash
|
||||
composer require "silverstripe/blog" "1.1.0"
|
||||
```bash
|
||||
composer require silverstripe/blog 1.1.0
|
||||
```
|
||||
|
||||
<div class="info" markdown="1">
|
||||
To lock down to a specific version, branch or commit, read up on
|
||||
For more information on using Composer version constraints, please [see here](https://getcomposer.org/doc/articles/versions.md). To lock down to a specific version, branch or commit, read up on
|
||||
[Composer "lock" files](http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file).
|
||||
</div>
|
||||
|
||||
@ -107,20 +111,21 @@ The SilverStripe module standard defines a set of conventions that high-quality
|
||||
|
||||
### Coding Guidelines
|
||||
|
||||
* Declaration of level of support is provided for each module (either via README.md or composer) including the below.
|
||||
* Declaration of level of support is provided for each module (either via README.md or composer) including the following:
|
||||
* Level of support provided.
|
||||
* Supporting user(s) and/or organisation(s).
|
||||
* Complies to a well defined module directory structure and coding standards:
|
||||
* templates (for ss templates)
|
||||
* code (for php files)
|
||||
* tests (for php test files) and
|
||||
* _config (for yml config)
|
||||
* `templates/` (for `.ss` templates)
|
||||
* `src/` (for `.php` files)
|
||||
* `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. ^3.1 not >=3.1).
|
||||
* All Composer dependencies are bound to a single major release (e.g. `^4.0` not `>=4` or `*`).
|
||||
* There is a level of test coverage.
|
||||
* A clear public API documented in the docblock tags.
|
||||
* Recommend the use of [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/).
|
||||
* .gitattributes will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.
|
||||
* Code follows [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/) style guidelines.
|
||||
* `.gitattributes` will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.
|
||||
* Add a [PSR-4 compatible autoload reference](https://getcomposer.org/doc/04-schema.md#psr-4) for your module.
|
||||
|
||||
### Documentation Guidelines
|
||||
|
||||
@ -129,14 +134,14 @@ Documentation will use the following format:
|
||||
* README.md provides:
|
||||
* Links or badges to CI and code quality tools.
|
||||
* A short summary of the module, end-user.
|
||||
* Installation instructions
|
||||
* Testing/development instructions and a link to contrib instructions.
|
||||
* Installation instructions.
|
||||
* Testing/development instructions and a link to contributing instructions.
|
||||
* How to report security vulnerabilities. Note that PSR-9 / PSR-10 may be recommended once released.
|
||||
* Security, license, links to more detailed docs.
|
||||
* CONTRIBUTING.md explaining terms of contribution.
|
||||
* A changelog CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could [use a changelog generator](https://github.com/skywinder/Github-Changelog-Generator) to help create this.
|
||||
* A changelog: CHANGELOG.md (may link to other more detailed docs or GitHub releases if you want). You could [use a changelog generator](https://github.com/skywinder/Github-Changelog-Generator) to help create this.
|
||||
* Has a licence (LICENSE.md file) - for SilverStripe supported this needs to be BSD.
|
||||
* Detailed documentation in /docs/en as a nested set of GitHub-compatible Markdown files.
|
||||
* Detailed documentation in `/docs/en` as a nested set of GitHub-compatible Markdown files.
|
||||
* It is suggested to use a documentation page named `userguide.md` in `docs/en/` that includes documentation of module features that have CMS user functionality (if applicable). For modules with large userguides, this should be in a directory named `userguide` with an `index.md` linking to any other userguide pages.
|
||||
* Links and image references are relative, and are able to be followed in viewers such as GitHub.
|
||||
* Markdown may include non-visible comments or meta-data.
|
||||
@ -146,7 +151,7 @@ Documentation will cover:
|
||||
* Installation
|
||||
* Configuration
|
||||
* Usage guides for key features; screenshots are recommended.
|
||||
* A committers guide, covering PR-merging and release guidelines.
|
||||
* A committers guide, covering pull request merging and release guidelines.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@ -1,45 +1,76 @@
|
||||
title: Upgrading
|
||||
introduction: Keep your SilverStripe installations up to date with the latest fixes, security patches and new features.
|
||||
|
||||
# Upgrading to SilverStripe 3.2
|
||||
# Upgrading to SilverStripe 4
|
||||
|
||||
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to your SilverStripe installation means overwriting files, flushing the cache and updating your database-schema.
|
||||
SilverStripe applications should be kept up to date with the latest security releases. Usually an update or upgrade to your SilverStripe installation means overwriting files, flushing the cache and updating your database schema.
|
||||
|
||||
<div class="info" markdown="1">
|
||||
See our [upgrade notes and changelogs](/changelogs/3.2.0) for 3.2.0 specific information, bugfixes and API changes.
|
||||
See our [upgrade notes and changelogs](/changelogs/4.0.0) for 4.0.0 specific information, bugfixes and API changes.
|
||||
</div>
|
||||
|
||||
## Composer
|
||||
|
||||
For projects managed through Composer, update the version number of `framework` and `cms` to `^3.2` in your `composer.json` file and run `composer update`.
|
||||
For projects managed through Composer, update the version number of `framework` and `cms` to `^4.0` in your `composer.json` file and run `composer update`.
|
||||
|
||||
```json
|
||||
"require": {
|
||||
"silverstripe/framework": "^3.2",
|
||||
"silverstripe/cms": "^3.2"
|
||||
}
|
||||
"require": {
|
||||
"silverstripe/framework": "^4.0",
|
||||
"silverstripe/cms": "^4.0"
|
||||
}
|
||||
```
|
||||
|
||||
<div class="info" markdown="1">
|
||||
Please note that until SilverStripe 4 is stable you will need to also add `"minimum-stability": "dev"` and `"prefer-stable": true` to your `composer.json` to be able to pull these modules.</div>
|
||||
|
||||
This will also add extra dependencies, the `reports` and `siteconfig` modules. SilverStripe CMS is becoming more modular, and [composer is becoming the preferred way to manage your code](/getting_started/composer).
|
||||
|
||||
### Asset-admin
|
||||
|
||||
SilverStripe 4 comes with a new asset administration module. While it is installed by default for new projects, if you are upgrading you will need to install it manually:
|
||||
|
||||
```
|
||||
composer require silverstripe/asset-admin ^1.0
|
||||
```
|
||||
|
||||
This will also install the `graphql` module for GraphQL API access to your SilverStripe system, which powers the `asset-admin` module.
|
||||
|
||||
## Manual
|
||||
|
||||
* Check if any modules (e.g. blog or forum) in your installation are incompatible and need to be upgraded as well
|
||||
* Backup your database content
|
||||
* Backup your webroot files
|
||||
* Download the new release and uncompress it to a temporary folder
|
||||
* Check if any modules (e.g. `blog` or `forum`) in your installation are incompatible and need to be upgraded as well.
|
||||
* Backup your database content.
|
||||
* Backup your webroot files.
|
||||
* Download the new release and uncompress it to a temporary folder.
|
||||
* Leave custom folders like *mysite* or *themes* in place.
|
||||
* Identify system folders in your webroot (`cms`, `framework` and any additional modules).
|
||||
* Delete existing system folders (or move them outside of your webroot)
|
||||
* Extract and replace system folders from your download (Deleting instead of "copying over" existing folders ensures that files removed from the new SilverStripe release are not persisting in your installation).
|
||||
* As of SilverStripe CMS 3.2.0 you will also need to include the `reports` and `siteconfig` modules to ensure feature parity with previous versions of the CMS.
|
||||
* Delete existing system folders (or move them outside of your webroot).
|
||||
* Rename your `Page_Controller` class to `PageController`.
|
||||
* Add a `private static $table_name = 'MyDataObject'` for any custom DataObjects in your code that are namespaced. This ensures that your database table name will be `MyDataObject` instead of `Me\MyPackage\Model\MyDataObject` (your namespace for the class).
|
||||
* Ensure you add [namespaces](http://php.net/manual/en/language.namespaces.php) to any custom classes in your `mysite` folder. Your namespaces should follow the pattern of `Vendor\Package` with anything additional defined at your discretion. **Note:** The `Page` and `PageController` classes *must* be defined in the global namespace (or; without a namespace).
|
||||
* Install the updated framework, CMS and any other modules you require by updating your `composer.json` configuration and running `composer update`. As of SilverStripe 4.0.0 you should also include the `asset-admin` module to power your asset management in the CMS.
|
||||
* Check if you need to adapt your code to changed PHP APIs. For more information please refer to [the changelog](/changelogs/4.0.0). There is an upgrader tool available to help you with most of the changes required (see below).
|
||||
* Visit http://yoursite.com/dev/build/?flush=1 to rebuild the website database.
|
||||
* Check if you need to adapt your code to changed PHP APIs
|
||||
* Check if you have overwritten any core templates or styles which might need an update.
|
||||
|
||||
<div class="warning" markdown="1">
|
||||
Never update a website on the live server without trying it on a development copy first.
|
||||
Never update a website on the live server without trying it on a development copy first!
|
||||
</div>
|
||||
|
||||
## Using the upgrader tool
|
||||
|
||||
We've developed [an upgrader tool](https://github.com/silverstripe/silverstripe-upgrader) which you can use to help you with the upgrade process to SilverStripe 4. [See the upgrading notes](/changelogs/4.0.0/#a-name-upgrading-a-upgrading) in the changelog for more detailed instructions on how to use it.
|
||||
|
||||
## Quick tips
|
||||
|
||||
If you've already had a look over the changelog, you will see that there are some fundamental changes that need to be implemented to upgrade from 3.x. Here's a couple of the most important ones to consider:
|
||||
|
||||
* PHP 5.5 is now the minimum required version (and PHP 7.x is supported!).
|
||||
* All SilverStripe classes are now namespaced, and some have been renamed. Most of your modules will also have been namespaced, and you will need to consider this when updating class references (including YAML configuration) in your own code.
|
||||
* CMS CSS has been re-developed using Bootstrap 4 as a base.
|
||||
* SilverStripe code _should_ now be [PSR-2 compliant](http://www.php-fig.org/psr/psr-2/). While this is not a requirement, we strongly suggest you switch over now. You can use tools such as [`phpcbf`](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automatically) to do most of it automatically.
|
||||
|
||||
We've also introduced some best practices for module development. [See the Modules article](/developer_guides/extending/modules) for more information.
|
||||
|
||||
## Decision Helpers
|
||||
|
||||
How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user