Define Blueprint Metadata for Blueprints Gallery v1

[adamziel]

What metadata is useful to keep track of? For now we have:

• Title – A clear and concise name for the Blueprint.
• Description – A brief explanation of what your Blueprint offers.
• Author – GitHub username.
• Categories – for future filtering. Which categories should be allowed? Perhaps this could be omitted from v1 and added later on once there's more Blueprints and some categories emerge naturally.

Would Blueprint version, similar to a plugin version, be useful at all? I'm not sure. Semantic versioning, as in 0.1.17 makes sense for software packages, but it doesn't seem to make sense for Blueprints. Also, contrary to plugins, there is nothing to auto-update after a new Blueprint is released.

[ironnysh]

• Categories: I vote for either categories or keywords/tags to help people filter by use case: show me only theme demos, Blueprints for educational purposes, testing a plugin, etc. Something like the Feature filter of the Theme Directory would be very helpful.

• Versions: this might make sense for situations where the author wants to share an updated Blueprint.

[adamziel]

Versions: this might make sense for situations where the author wants to share an updated Blueprint.

@ironnysh they could update that Blueprint via a PR, I wonder if explicitly the keeping track of the version number buys us anything here.

[ironnysh]

Hey @adamziel, I might be missing something 😀

Here's the scenario I imagined:

1. I create a Blueprint and submit it to the Gallery.
2. Two months later, I change something (could be minor or major, to stick with version release terminology).
3. I submit a PR with the updated Blueprint. It still has the same metadata, though.
4. It's approved and added to the Gallery.

My questions:

• What happens to the previous one?
• What would people visiting the Gallery see? The newest version, both?
• Would there be any changelog or other indication that something has changed?

[adamziel]

What happens to the previous one?

It would be replaced by the new one. The previous version would still be available via git history.

What would people visiting the Gallery see? The newest version, both?

The newest version. Do you think exposing both could be useful?

Would there be any changelog or other indication that something has changed?

Git commit messages would form one, perhaps we could associate a CHANGELOG.md file with each Blueprint and update it automatically with a PR title and link on each change 🤔 I wonder what would it be useful for, though.

[adamziel]

@ironnysh just pinging to follow up :-)

[ironnysh]

Oh, sorry, I must've missed the notification on this one :-)

Do you think exposing both could be useful?

I guess it depends on how extensive are the changes to the Blueprints.

associate a CHANGELOG.md file with each Blueprint and update it automatically with a PR title and link on each change

Thinking about a future situation, when people use Blueprints from the gallery in their live projects:
If, for example, they link directly to a blueprint.json using the raw.githubusercontent.com domain, and suddenly the theme changed, or the admin notice has moved to another page, or any other—seemingly random and arbitrary—modification was made.
It'll affect their project, and they wouldn't know why. This way, they will at least have a “paper trail”.

Does that make sense?

[adamziel]

If, for example, they link directly to a blueprint.json using the raw.githubusercontent.com domain, and suddenly the theme changed, or the admin notice has moved to another page, or any other—seemingly random and arbitrary—modification was made.

@ironnysh oh interesting! This touches a deeper issue – should we use permalinks or link to the latest version of Blueprints and their related resources.

1. Use permalinks for all the Blueprints and their embedded resources, e.g. https://raw.githubusercontent.com/adamziel/blueprints/6b473ed/blueprints/custom-post/blueprint.json. These Blueprints will never change which means you won't be surprised, but you also won't get auto updates.
2. Use trunk links, e.g. https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/custom-post/blueprint.json. These may change without warning, but you'll benefit from bugfixes and auto updates.

I am leaning towards generally recommending the first one, but documenting the second one as a possible choice if the reader is okay with the downsides.

It'll affect their project, and they wouldn't know why. This way, they will at least have a “paper trail”.

My thinking was we could GitHub history for that as it provides a list of changes, their description, time of commit, and author, e.g. here:

https://github.com/adamziel/blueprints/commits/trunk/blueprints/posts-via-wp-cli/blueprint.json

[ironnysh]

I am leaning towards generally recommending the first one, but documenting the second one as a possible choice if the reader is okay with the downsides.

I like it. +1 :-)

we could GitHub history for that

Yes, definitely. And the format/workflow will be what you mentioned above?

associate a CHANGELOG.md file with each Blueprint and update it automatically with a PR title and link on each change

[bph]

Version numbers for blueprints don't seem to have a particular purpose except for historical value. My understanding is that the blueprints in the gallery are just examples that people will copy, modify and to their needs. Even if two months from now, I update one of the examples, the earlier usage is disconnected from the new version anyway. It's not like an npm dependency, or a plugin dependency that could cause havoc when updated over the network. So I agree that the commit history should be enough to follow up on historical information.

I would actually tend to opt for the second variation, the /trunk/ as that's. the official current version of the blueprint. It also helps creators to have a consistent way to link to think. The link is fully understandable, and doesn't include a random string in the middle of it. Readability is a value to to be underestimated.
As a rule, it is also easier to understand and to explain.

I would have that as a default setting and if someone using the blueprints wants to use the gallery version in their projects for good, it's their responsibility to keep up with changes, like with any other dependency they add to their technical debt.
So make the default to link to trunk and make the commit related one as one to be documented.

Using the /trunk/ links would also be consistent with other directory usage of the asset that also go back to the /trunk/ version, and everything in the directory of a blueprint uses the same link pattern:

As example:
https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/cli-markdown/postcontent.md
https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/cli-markdown/Select-storage-method.png

All assets are referenced in the
https://raw.githubusercontent.com/adamziel/blueprints/trunk/blueprints/cli-markdown/blueprint.json
The link pattern can also be created dynamically, which isn't the case when you link to a commit string in between.

--
links will work after this PR is merged

[ironnysh]

Glad you joined in, @bph, awesome points! :-)

My understanding is that the blueprints in the gallery are just examples that people will copy, modify and to their needs.

I believe this is the core difference: I was thinking about the Blueprint Gallery as the equivalent of the Themes/Plugins directory, while your perspective is closer to the Patterns directory. In this case, using trunk would definitely be the way to go.

Using the /trunk/ links would also be consistent with other directory usage of the asset

Good point. I haven't thought of that.

if someone using the blueprints wants to use the gallery version in their projects for good, it's their responsibility to keep up with changes

Whichever model we end up with, it's crucial to communicate it and make sure people understand the pros and cons of each option.

[adamziel]

A lot of great points here, that's perfect! It seems like we're good to close this issue and move forward with Title, Description, Author, and Categories as the initial metadata fields, and we can always add new ones once they won't be sufficient.

if someone using the blueprints wants to use the gallery version in their projects for good, it's their responsibility to keep up with changes
Whichever model we end up with, it's crucial to communicate it and make sure people understand the pros and cons of each option.

@bph would you please make a note of this in the contributing documentation? Thank you!