Skip to content

Commit

Permalink
DOCS Review extending docs for truthfulness (#273)
Browse files Browse the repository at this point in the history
  • Loading branch information
@GuySartorelli
GuySartorelli authored Jun 13, 2023
1 parent 8d115f3 commit 08f04c8
Show file tree
Hide file tree
Showing 10 changed files with 496 additions and 529 deletions.
17 changes: 2 additions & 15 deletions en/00_Getting_Started/03_Environment_Management.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,21 +73,8 @@ Environment::setEnv('API_KEY', 'AABBCCDDEEFF012345');

### Using environment variables in config

To use environment variables in `.yaml` configs you can reference them using backticks. You can have multiple
environment variables within a single value, though the overall value must start and end with backticks.

```yaml
SilverStripe\Core\Injector\Injector:
MyServiceClass:
properties:
MyProperty: '`ENV_VAR_ONE`'
MultiValueProperty: '`ENV_VAR_ONE`:`ENV_VAR_TWO`'
ThisWillNotSubstitute: 'lorem `REGULAR_TEXT` ipsum'
```
[warning]
Environment variables cannot be used outside of Injector config.
[/warning]
To use environment variables in `.yaml` configs you can reference them using backticks. This only works in `Injector` configuration.
See the [Injector documentation](/developer_guides/extending/injector/#using-constants-and-environment-variables) for details.

## Including an extra .env file

Expand Down
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ class Player extends DataObject
* `'Foreignkey'`: A special `Int` field used for foreign keys in `has_one` relationships (see: [DBForeignKey](api:SilverStripe\ORM\FieldType\DBForeignKey)).
* `'HTMLFragment'`: A variable-length string of up to 2MB, designed to store HTML. Doesn't process [shortcodes](/developer_guides/extending/shortcodes/). (see: [DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText)).
* `'HTMLText'`: A variable-length string of up to 2MB, designed to store HTML. Processes [shortcodes](/developer_guides/extending/shortcodes/). (see: [DBHTMLText](api:SilverStripe\ORM\FieldType\DBHTMLText)).
* `'HTMLVarchar'`: A variable-length string of up to 255 characters, designed to store HTML (see: [DBHTMLVarchar](api:SilverStripe\ORM\FieldType\DBHTMLVarchar)).
* `'HTMLVarchar'`: A variable-length string of up to 255 characters, designed to store HTML. Can process [shortcodes](/developer_guides/extending/shortcodes/) with additional configuration. (see: [DBHTMLVarchar](api:SilverStripe\ORM\FieldType\DBHTMLVarchar)).
* `'Int'`: A 32-bit signed integer field (see: [DBInt](api:SilverStripe\ORM\FieldType\DBInt)).
* `'Locale'`: A field for storing locales (see: [DBLocale](api:SilverStripe\ORM\FieldType\DBLocale)).
* `'Money'`: Similar to Currency, but with localisation support (see: [DBMoney](api:SilverStripe\ORM\FieldType\DBMoney)).
Expand Down
153 changes: 70 additions & 83 deletions en/02_Developer_Guides/05_Extending/00_Modules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,13 @@ framework.
A module is a collection of classes, templates, and other resources that is loaded into a directory.
Modules are [Composer packages](https://getcomposer.org/), and are placed in the `vendor/` folder.
These packages need to contain either a toplevel `_config` directory or `_config.php` file,
as well as a special `type` in their `composer.json` file ([example](https://github.com/silverstripe/silverstripe-module/blob/4/composer.json)).
as well as a special `type` in their `composer.json` file ([example](https://github.com/silverstripe/silverstripe-module/blob/5/composer.json)).

Like with any Composer package, we recommend declaring your PHP classes through
[PSR autoloading](https://getcomposer.org/doc/01-basic-usage.md#autoloading).
[PSR-4 autoloading](https://getcomposer.org/doc/01-basic-usage.md#autoloading).
Silverstripe CMS will automatically discover templates and configuration settings
within your module when you next flush your cache.


## Finding Modules

* [Official module list on silverstripe.org](https://addons.silverstripe.org/)
Expand All @@ -38,17 +37,15 @@ identifier `silverstripe/blog` as it is published by *silverstripe*. To install,
the project root folder:

```bash
composer require silverstripe/blog *@stable
composer require silverstripe/blog
```

This will fetch the latest compatible stable version of the module. To install a specific version of the module give the
tag name.
This will fetch the latest compatible stable version of the module.

```bash
composer require silverstripe/blog 1.1.0
```
Composer uses [version constraints](https://getcomposer.org/doc/articles/versions.md). You can declare a specific constraint to install
if you want to, but typically if you leave the constraint blank Composer will correctly detect an appropriate constraint for you based
on your project's stability configuration.

Composer is using [version constraints](https://getcomposer.org/doc/articles/versions.md).
To lock down to a specific version, branch or commit, read up on
["lock" files](https://getcomposer.org/doc/01-basic-usage.md#commit-your-composer-lock-file-to-version-control).

Expand All @@ -60,103 +57,99 @@ After you add or remove modules, make sure you rebuild the database, class and c

Creating a module is a good way to re-use code and templates across multiple projects,
or share your code with the community. Silverstripe CMS already
has certain modules included, for example the `cms` module and core functionality such as commenting and spam protection
has certain modules included, for example the `cms` module and various functionality such as commenting and spam protection
are also abstracted into modules allowing developers the freedom to choose what they want.

### Create a new directory
### Create a new repository

The easiest way to get started is our [Module Skeleton](https://github.com/silverstripe/silverstripe-module).

First, create a new directory named after your intended module in your main project. It should sit alongside the other modules
such as *silverstripe/framework* and *silverstripe/cms* and use it for the module development:
You can create a new repository based on the skeleton using the ["Use this template"](https://github.com/silverstripe/silverstripe-module/generate) function on GitHub.

`mkdir /vendor/my_vendor/module_name`
### Allow your module to be importable by Composer

Then clone the Module Skeleton to get a headstart with the module files:

```bash
cd /vendor/my_vendor/module_name
git clone [email protected]:silverstripe/silverstripe-module.git .
```
You could import your project using Composer right away - but the name in your `composer.json` file is still "silverstripe-module/skeleton"
instead of being the appropriate name for your module.

### Allow your module to be importable by composer
You can either edit the file directly in GitHub, or you can clone the repository to a temporary directory - but bare in mind you'll only be
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.

You need to set your module up to be importable via composer. For this, edit the new `composer.json` file in the root of
your module. Here is an example for a module that builds on the functionality provided by the `blog` main module (hence the
requirement):
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:

```json
{
"name": "my_vendor/module_name",
"description": "Short module description",
"type": "silverstripe-vendormodule",
"require": {
"silverstripe/cms": "^5.0",
"silverstripe/framework": "^5.0",
"silverstripe/blog": "^5@dev"
"silverstripe/cms": "^5.0",
"silverstripe/blog": "^5.0"
}
}
```

After your module is running and tested, you can publish it. Since your module is a self-contained piece of software, it
will constitute a project in itself. The below assumes you are using GitHub and have already created a new GitHub repository for this module.

Push your module upstream to the empty repository just created:
Commit your change, and if you chose to make this change locally on your computer, push the changes back up to GitHub. You can delete the temporary
directory now, if you created one.

```bash
git init
git add -A
git commit -m 'first commit'
git remote add origin [email protected]:my_vendor/module_name.git
git push -u origin main
```
### Add the module to a project for development

Once the module is pushed to the repository you should see the code on GitHub. From now on it will be available for
others to clone, as long as they have access (see the note below though: private modules are not deployable).
To develop the module, you'll want to include it in a Silverstripe CMS project. It's up to you whether you
do this in a project you already have set up, or start a new one from scratch specifically for this purpose.
In most cases we recommended using a new project, at least at first.

### Including a private module in your project
If this is a module you intend to be available publicly, it might make sense to submit the repository to
[Packagist](https://packagist.org/) at this stage.

Including public or private repositories that are not indexed on **Packagist** is different from simply using the `composer require silverstripe/blog` command. We will need to point *composer* to specific URLs. Background information can be found at
[Working with project forks and unreleased
modules](../../getting_started/composer/#working-with-project-forks-and-unreleased-modules).
[note]
If you want your module to be private or for some reason don't want to publish it in packagist just yet,
see [Including a private module in your project](#including-a-private-module-in-your-project) below.
[/note]

For our *nice_module* example module we have just pushed upstream and can add the following lines to your `composer.json` file in the root directory of your main project.
Once you've done that, you can simply install it like
you would any other dependency - just make sure you use the `--prefer-source` option, which will ensure
Composer installs the module directly from GitHub and keeps the initialised local git repository.

```json
"repositories": [
{
"type": "vcs",
"url": "[email protected]:my_vendor/module_name.git",
}
]
```sh
composer require my_vendor/module_name:dev-main --prefer-source
```

This will add the repository to the list of URLs composer checks when updating the project dependencies. Hence you can
now include the following requirement in the same `composer.json`:
[hint]
The `dev-main` portion of the above command above is a version constraint which tells Composer to install your module from the `main` branch.
If you are using a different branch name, you should use the correct branch here instead (e.g. if the branch name is `development`, the constraint
will be `dev-development`).
[/hint]

```
"require": {
...
"my_vendor.module_name": "*"
}
```
Once Composer has installed the module, you can develop your module in the `vendor/my_vendor/module_name` directory,
and commit/push changes from there to the remote repository in GitHub.

Add the module directory name (`module_name/`) to `.gitignore` - we will rely on *composer* to update the dependencies so
we don't need to version-control it through the main repository.
#### Including a private module in your project

Run `composer update` to pull the module in and update all other dependencies as well. You can also update just this one
module by calling `composer update my_vendor/module_name`.
Including public or private repositories that are not indexed on **Packagist** is different from simply using the `composer require` command. We will need to point Composer to specific URLs. Background information can be found at
[Working with project forks and unreleased modules](../../getting_started/composer/#working-with-project-forks-and-unreleased-modules).

If you get cryptic composer errors it's worth checking that your module code is fully pushed. This is because composer
can only access the code you have actually pushed to the upstream repository and it may be trying to use the stale
versions of the files. Also, update composer regularly (`composer self-update`). You can also try deleting Composer
cache: `rm -fr ~/.composer/cache`.
For our example module you can add the following lines to your `composer.json` file in the root directory of your main project.

[notice]
This goes into the `composer.json` for the Silverstripe CMS project where you're installing your module, _not_ into the `composer.json` of your module itself.
[/notice]

Finally, commit the the modified `composer.json`, `composer.lock` and `.gitignore` files to the repository. The
`composer.lock` serves as a snapshot marker for the dependencies - other developers will be able to `composer install`
exactly the version of the modules you have used in your project, as well as the correct version will be used for the
deployment. Some additional information is available in the [Deploying projects with
composer](https://docs.silverstripe.org/en/4/getting_started/composer/#deploying-projects-with-composer).
```json
"repositories": [
{
"type": "vcs",
"url": "[email protected]:my_vendor/module_name.git",
}
]
```

This will add the repository to the list of URLs Composer checks when updating the project dependencies. You can
now include the dependency as normal, e.g:

```sh
composer require my_vendor/module_name:dev-main --prefer-source
```

### Open-sourcing your creation for the community to use

Expand All @@ -171,18 +164,17 @@ which the Silverstripe CMS project applies to the modules it creates and maintai

### Coding Guidelines

* 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)
* `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. `^5.0` not `>=5` or `*`).
* 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.
* There is a level of test coverage.
* Uses strong typing where appropriate.
* A clear public API documented in the docblock tags.
* If parameters and return values don't need additional description and are strongly typed, these should be ommitted from the docblock.
* Code follows [PSR-1](https://www.php-fig.org/psr/psr-1/) and [PSR-2](https://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.
Expand All @@ -195,14 +187,10 @@ Documentation will use the following format:
* 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 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.
* Has a licence (`LICENSE` file) - for Silverstripe CMS supported this needs to be BSD.
* 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.
* 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.

Expand All @@ -211,7 +199,6 @@ Documentation will cover:
* Installation
* Configuration
* Usage guides for key features; screenshots are recommended.
* A committers guide, covering pull request merging and release guidelines.

## Related

Expand Down
Loading

0 comments on commit 08f04c8

Please sign in to comment.