read me improvements necessary

[mrbm]

Readme is suggesting plugin can be installed a mu-plugin.

1)Simply dropping the folder in the mu-plugin directory will not work 2) creating an mu loader file with the following code:

require WPMU_PLUGIN_DIR.'/multisite-global-media/multisite-global-media.php';

Will not work because the following message:

No suitable autoloader found. Multisite Global Media cannot be loaded correctly.

So...problems my good friend!

Would love to know how to get this latest version working and so that I can be testing for the woocommerce conflict asap, thanks!

[mrbm]

So here's what I did to make the latest version run:

I had to manually create the composer.json file in the directory for the plugin for some reason when directly downloading the zip via the command line: wget https://github.com/bueltge/multisite-global-media/archive/master.zip

The file is not in there. So i manually re-create it from your github.com by simply copy and pasting the content into a file.

I then go into the directory after unzipping and run the command: composer install --no-dev --optimize-autoloader

That said, complete instructions are needed to get this working, just a heads up!

[bueltge]

Thanks for the hint. Since we had updated to use Composer for autoload and dependency management we had also change the readme. The last version, also betas (include a zip with autoload) are available inside the releases - https://github.com/bueltge/multisite-global-media/releases

Which readme do you read?

I create it always also via composer install --no-dev --optimize-autoloader

[bueltge]

Hi @mrbm have you read the comment from my side? Please read also the readme - you miss a part for the install of the current solution? If not I will close this issue.

[mrbm]

I am reading the readme posted here: https://github.com/bueltge/multisite-global-media below the list of files.

I think the general and expected method coming into this is people will read that email, and then perhaps download the file direct from the download button on that page.

But doing so will not render the results you are expecting.

SO....updates are needed.

I personally got it working, but it was unnecessarily frustrating.

Anyways still love the plugin, so thanks for putting it together :D

[widoz]

@mrbm Since this is a repository when you get the master copy you get the source code not the build.

Means there are additional steps to make the plugin ready to work and that's normal, if you want to download the build go to the https://github.com/bueltge/multisite-global-media/releases *Releases" page and download the build package.

The releases page always contains source version and build.

Doesn't make sense to add the vendor directory under version because this could contains a lot of additional files needed only during the development.

[widoz]

@bueltge May be we should clarify how to get the build package, effectively from the Readme isn't clear.

Download the plugin as zip (available inside the release), use a clone of the repo or use Composer, see below.

Could take a person to think all of them are valid way to obtain a build.

[mrbm]

@widoz agreed. The common presentation of wordpress plugin code for the master branch, is that it is showing the working plugin code. I think your master branch should be renamed, "master-pre-build"

Additionally the readme should be updated to be more explicit.

I'm a guy with "above" average wordpress experience...but the average user would have no chance.

[widoz]

@mrbm master it's still a branch and doesn't include build code/files, btw github is for developers and developers know hot to run/setup things, for all of the others I always suggest to use the build package because many things could happen, for example not only the autoloader but also javascript, files may be them need to be uglified, transformed or scss could be converted into css. Also consider all of the other files needed for development: phpunit.xml, phpcs.xml, composer.lock, composer.json, .lintrc, tests directories and many other files that have to not be included in a release package.

Composer is commonly used in various projects and its autoloader is usually stored within the build and not in the repo, for development we need to install not only packages used by the plugin in production but for development such as testing packages, linters, static analysis tools.

Including the autoloader would make the project difficult to maintain because you'll have to delete all of the dev dependencies every time you have to push something, the composer.lock could be updated during that operation and that's not good. We could use the map class autoloader but usually that not work properly in case a new class is created. Better to have a class map than a psr4 autoloader in production because it's faster.

If you download the master you are downloading source code, that's is, if you want to download the build you'll need to use the package build from the releases page in case of github or wp-packagist if the plugin is available there or require it using composer.

I agree the readme should be more explicit, may be a section that describe how to install the package by source code, composer or the build with a link to the latest stable package https://github.com/bueltge/multisite-global-media/releases/latest.

Something like:

How to install

Little description that explain differences about source code and package and where to download them. (Es link to the releases page)

Install Source Code

Instructions to make the plugin run by source code from git clone to composer install

Install using composer

How to require the package using composer, usually the preferred approach to install it as a dependency of a project. (You get the latest stable code or the version defined by the constraint)

Install using Package

Where to get the latest stable package version and the classic Wordpress informations.

We could add Pre-Release information since @bueltge I think would keep that approach.

[mrazzari]

A couple of related gotchas...

• I downloaded the release zip, which includes a required "vendor" dir, but it's .gitignore'd. So when I tried to commit the plugin to my project's private repo, it wasn't included. I committed a non-working plugin.
• It's not clear why install instructions strongly encourage usage as a must-use plugin. Having to install an extra plugin "Must Use Loader" seems overkill. And many projects don't want this plugin on all sites in the network.

[bueltge]

A must use is not necessary. The vendor is necessary, inside this directory is the autoloader to include and handle files.

[mrazzari]

Yes, I understand the issue from a code POV. What I'm trying to say is more about documentation and defaults.

• The way the release zip is built, it can't be committed as-is to another repo. The "vendor" dir is necessary, but if I commit the plugin to my project's own repo, the vendor dir won't be included. This is because the zip includes a .gitignore file to ignore the vendor dir. Within the "vendor" dir, the only directory that's really needed is the "composer" one. The zip also includes a .git dir that needs to be removed.
• the readme leads users down a confusing path. It "recommends use as Must Use plugin". Users that want this, will know how to get it. Doesn't seem worth mentioning.

[bueltge]

@mrazzari Thanks for your input. I will improve the release steps, script to reduce to the files there we need for a simple use plugin. Maybe you will change, improve the readme to understand the how to. The must use plugin is only helpful, if users have more must use plugins or the requirements to read plugins in the must use topic in sub-directories. The zip on the release page is updated, simplify.

The first try for a script is listed in #89