search

WordPress / blueprints

Blueprints gallery and examples
69 stars 25 forks source link

Blueprint meta: Add "More Information" type field #43

Open flexseth opened 6 months ago

flexseth commented 6 months ago

Recently I was working on a Blueprint from the Gallery, and wasn't sure if I had changed the code or if something wasn't working correctly. If there was a link to more info about the blueprint, that would be helpful!

Suggesting a new meta value, name TBD. Currently the standard is lowercase..

The source of truth and more information about the blueprint.

The URL could link to part of a repository for more info or a raw blueprint.json file (for simpler blueprints)

Sample

Run unit, accessibility, and theme review tests

"meta": {
        "title": "Theme Ready",
        "description": "Runs all theme tests and reports back",
        "author": "WP.org Themes Team",
        "categories": [
          "themes",
          "content"
        ],
        "link": "themetest.playground.wordpress.net"
      }, 
"steps": {
      ...
}

Where themetest.playground.wordpress.net provides more information about what the blueprint does

adamziel commented 6 months ago

Where themetest.playground.wordpress.net provides more information about what the blueprint does

what information could it provide beyond what’s in the meta section?

flexseth commented 6 months ago

Essentially I was thinking about a "More information" type field...

Use case

Let's say you found a Blueprint somewhere and want to work on it. You copy the code, do some modifications, but for some reason forget where the blueprint came from (this actually happened to me)

Having somewhat of a canonical link to the blueprint - where did it come from - would be a way to get back to more info on the steps provided. As blueprints grow in complexity, I'm just envisioning users wanting to know more about the steps involved. IE:

Blueprints documentation

Ideally, blueprint authors would find some way to document what the steps actually do, so if someone wanted to do something similar, they wouldn't have too much trouble.

Similar to the Plugin URI header field for plugins

Plugin URI: The home page of the plugin, which should be a unique URL, preferably on your own website. This must be unique to your plugin. You cannot use a WordPress.org URL here.

Thinking of those who are new to blueprints, giving a trail of breadcrumbs back to where they came from.

(Could be a GitHub repo)

... more info on Plugin Headers

Notes from my findings on possible structure for the new meta

ironnysh commented 6 months ago

That's basically an extension of the discussion we had in issue #3 🙂

flexseth commented 3 months ago

Maybe a link meta field?

link: Canonical link to the blueprint design, more information, or the actual blueprint JSON file.

Description: A link to a GitHub repo (README), link to a raw JSON file on someone's website, or a link to a full description about what the blueprint does, etc.