Documenting the "vendor expose" sorcery

silverstripe / developer-docs

Developer documentation for Silverstripe CMS

Other

6 stars 61 forks source link

Documenting the "vendor expose" sorcery #35

Open maxime-rainville opened 5 years ago

maxime-rainville commented 5 years ago

Affected Version

4 and above

Description

Following some discussion it appears the "vendor expose" process is not super clear for most of the SilverStripe community.

I suggest we fix this by providing a central doc article demystifying the vendor-expose logic.

Acceptance criteria

As a SilverStripe Developer I can understand:
- The purpose of "vendor-expose",
- How to expose my project resources,
- How to reference project resources and module resources in templates and php files,
- How to debug common issues with vendor expose
As a SilverStripe Module Developer I can understand:
- How to expose my module's resources and reference them.

maxime-rainville commented 5 years ago

This is kind of related to https://github.com/silverstripe/silverstripe-framework/issues/7932

I'm thinking the outline of the document could look something like that.

Overview
- Why do I need to expose static resources
- What does vendor-expose actually do
How to refresh expose files
- composer update/install
- composer vendor-expose
- vendor-plugin-helper
Customising behaviour
- Manually
- With SS_VENDOR_METHOD
- Where resources are expose in the webroot
Referencing exposed assets
- Explicitly with ModuleLoader
- Implicitly with vendor/module: path/to/my/file.txt format
- Reference Theme resources
- Reference resource in tempalte files
How to expose files
- For my project
- For my module

There's a bit of this in the upgrading guide, but it narrowly focus on how to update your SS3 project to work, not so much on how this thing works. https://docs.silverstripe.org/en/4/upgrading/#step9

lerni commented 5 years ago

It would also be helpful to outline how to locally handle expose during development of a vendormodule before its in composer/packagist. Luckily I'm working with a symlink-able system ;)

maxime-rainville commented 5 years ago

This commit https://github.com/silverstripe/silverstripe-framework/commit/542842791ea8f0b18b37d39d15a26c143e44bc2b on PR https://github.com/silverstripe/silverstripe-framework/pull/8519#issuecomment-451807616 partially addresses this issue.

There's probably other aspects to clean up on the Requirements DOC.

tractorcow commented 5 years ago

A little bit of docs are on the plugin itself at https://github.com/silverstripe/vendor-plugin.

Similarly recipe files can be a bit magical. Quite a few docs at https://github.com/silverstripe/recipe-plugin that could be core-ified at the same time.

maxime-rainville commented 5 years ago

Yes, I agree there's a bit of sorcery involved in the recipe-plugin as well. It probably would help if we had a general convention about what doc needs to be on the package and what needs to be in the core doc.

Probably something like:

Usage doc goes in core,
Information needed to do active development on the module goes in the package's README.

robbieaverill commented 5 years ago

It would also be helpful to outline how to locally handle expose during development of a vendormodule before its in composer/packagist. Luckily I'm working with a symlink-able system ;)

@lerni A developer I was working with last year said he used this for local development: https://github.com/franzliedke/studio

It's also worth noting that you can develop modules as regular silverstripe-module types rather than vendor modules until you're ready to publish them to Packagist. The way you expose and require resources from them shouldn't change between the types.

maxime-rainville commented 5 years ago

https://github.com/silverstripe/silverstripe-framework/commit/728c982de2e62adfa560fd7435679782cdd9aecd Fixed must of the points on this issue.