Including Readme on the extension/theme page

PhillippOhlandt commented 8 years ago

Hey,

most extensions/themes have just one or two sentences as description but a good Readme with all instructions you need. Maybe we can include it on the extension/theme page so a user can stay on that page and don't have to move to github?

rossriley commented 8 years ago

The import already fetches the readme info in, so adding would be pretty easy. The only reason I didn't output it is the problem of versions, since theoretically each version or release has a different version of the README.md file, so knowing which one to use as the canonical one on the extensions page can be a bit of a problem.

We could just show whatever the master version of README.md is, as long as that wouldn't cause any issues for people.

PhillippOhlandt commented 8 years ago

I would use the readme of the latest version because that will be the version the user would pull in.

SvanteRichter commented 8 years ago

Wouldn't it be better if the description supported markdown so that we could write better descriptions that way? Perhaps even a tagline field to use in listings and only show the description on the individual screen. The readme is more "how to use" rather than "why to use".

PhillippOhlandt commented 8 years ago

But "how to use" is the important thing, isn't it?

Otherwise we can go crazy and support markdown but provide a button to automatticly import the readme.

Or the user can chose if he want write an extra description for the store or want to display the readme from the latest stable version.

SvanteRichter commented 8 years ago

"How to use" is important once it is installed. "Why" is important when selecting/discovering extensions. Once it is installed you have access to the readme from the backend (where you actually need to know "how").

Or the user can chose if he want write an extra description for the store or want to display the readme from the latest stable version.

I like this idea, seems like the best of both worlds :)

PhillippOhlandt commented 8 years ago

Great! Let's stick with that! :)

ghost commented 8 years ago

"How to use" is important once it is installed. "Why" is important when selecting/discovering extensions.

I beg to differ. The current 1 or 2-liner "why" is good as an intro shown in the search result list, but insufficient for the main page of an extension. Right now I know that I'll have to leave Bolt's extensions page each time and check the dev's repository to make sure that the extension does what I want in the way that I expect... by checking the readme.

Besides, a good readme should answer both the "why" and "how".

Once it is installed you have access to the readme from the backend (where you actually need to know "how").

Install first ask later? Sounds like a bad idea to me.

Or the user can chose if he want write an extra description for the store or want to display the readme from the latest stable version.

Pull the readme only, there's less chances of outdated/mismatching descriptions.

SvanteRichter commented 8 years ago

@kehugter The current solution isn't enough, we agree about that, but I really think that "why" and "how" should be two different things here. Rendering the readme on the extensions site would be good, but I think there should also be room for a separate text that explains the usecase before diving into the readme. Perhaps having two tabs, one for description and one for the readme on each detail page would suffice? That way we could just show the readme if it hasn't got a description, and it would be up to the extension author to decide.

PhillippOhlandt commented 8 years ago

On boltthemes I just included both because it can't hurt. https://boltthem.es/theme/spatial

ghost commented 8 years ago

@SahAssar what about implementing a simple parser and providing a template for the readme? I think most devs would find it more convenient and natural than having to keep the readme and extensions.bolt.cm page synchronised. If the readme can't be parsed, fall back to the local description and full readme.

Is also convenient for the users: you know where to find the information you need in any bolt extension/theme. If they find an error, a patch can be committed, unlike in extensions.bolt.cm.

Grav implemented this kind of approach nicely for extensions and themes. They fetch basic information from different files in the repo as described in the docs. A structured file (blueprints.yaml in their case) is even better than parsing the readme. A standardised readme could be encouraged anyway, as mentioned before.

SvanteRichter commented 8 years ago

@kehugter That sounds like something that would be great to have in the composer.json since we already define locations for extension icons and screenshots there in the extras section, how about something like this:

"extra": {
    "bolt-screenshots": [
        "screenshots/listing.jpg",
        "screenshots/home.jpg"
    ],
    "bolt-assets": "assets",
    "bolt-icon": "assets/icon.png",
    "readme": "readme.md",
    "description": "description.md"
}

ghost commented 8 years ago

Looks good to me but don't take my word for it, I'm a newcomer at bolt.

Some theoretical issues/improvements:

extra has already a specific purpose and shouldn't be touched, meta could be used instead for the new fields
description could be long, summary assures a concise text (the field would be documented, I'm just being fussy about the name)

GwendolenLynch commented 8 years ago

Looks good to me but don't take my word for it, I'm a newcomer at bolt.

Exactly why your input is very useful… we're too used to looking at the same thing! :+1:

PhillippOhlandt commented 8 years ago

extra has already a specific purpose and shouldn't be touched, meta could be used instead for the new fields

As long as we prefix everything with bolt-, I see no problems. And we can't change it easily because everything (all packages, extension store, bolt itself) uses it.

What I think: It looks like we try to make it more complicated than it could be. The Problem: All the documentation about the package is inside the readme and people just write a little description text on the extension store. Simplest solution: Just include the readme in the extension store. Maybe we let the dev choose if he wants to have it included or not.

Adding more meta is always good but there is no need to define the readme file. Github knows what the readme file is (readme.md, README.md, Readme.md, etc ...), and you can ask Github for that via an API. I also think there is no need to define a description or summary of the package inside the package itself. The extension store is a good place to hold that data.

GwendolenLynch commented 8 years ago

I'm with you @PhillippOhlandt … adding more configuration to the JSON file will just mean that nobody does it.

The GitHub API sounds like the way to go for me.

SvanteRichter commented 8 years ago

@kehugter: Looks to me like extra can be mostly anything that is meant to be consumed by scripts:

Arbitrary extra data for consumption by scripts. This can be virtually anything. To access it from within a script event handler, you can do:

https://getcomposer.org/doc/04-schema.md#extra

@PhillippOhlandt didn't you have a problem with getting the right readme file when working on bolthem.es?

Also, the point of having it in the package is that it can be versioned and there can be PR's/whatever against it.

PhillippOhlandt commented 8 years ago

@SahAssar Nope, not with the github api: https://api.github.com/repos/JustSteveKing/Bolt-Medium/readme

Also, the point of having it in the package is that it can be versioned and there can be PR's/whatever against it.

I don't think a two sentences summary has to be versioned and maintained by everyone.

ghost commented 8 years ago

Github knows what the readme file is [...] and you can ask Github for that via an API

Perfect, agree that it can be removed from the config.

Maybe we let the dev choose if he wants to have it included or not.

You need a good excerpt for the search results. I wouldn't make it optional.

The extension store is a good place to hold that data.

Some thoughts about that

If the summary is mandatory, I'd personally prefer to add it during my usual workflow (ie, my editor) than going trough the extra clicks elsewhere . If the extension template includes that field, the process is perfectly natural.
In case you have to update the description, doing it locally is certainly more convenient than logging in at extensions.bolt.
The summary can be fetched from bolt's backend, improving the installation UX.
In case of a migration or an external project indexing bolt's extensions, the less data depending on your own database, the better. It also assures a smooth project continuity in case all of you are abducted by aliens.

If the description consists only of one or 2 sentences, could it be just written inside composer.json? Or would that be bloating the file?

PhillippOhlandt commented 8 years ago

In case you have to update the description, doing it locally is certainly more convenient than logging in at extensions.bolt.

If you change it in your repo, you have to click the update button in the extension store anyway.

PhillippOhlandt commented 8 years ago

You need a good excerpt for the search results. I wouldn't make it optional.

You always have the description from the package on the extension store. I wouldn't use the readme as excerpt because it usually starts with the package name (and duplication sucks)

ghost commented 8 years ago

you have to click the update button

Can't extensions be hooked?

I wouldn't use the readme as excerpt

Agree, me neither.

PhillippOhlandt commented 8 years ago

Not yet. We are working on that.

bolt / site-market-bolt-cm

Including Readme on the extension/theme page #19