Snippet Repo

Your warning is valid, @joyously. In fact, that’s a lesson that CP has learned. But I don’t see that as a problem here.

In fact, what we’d be doing by using Github gists coupled with a CPT is emphasizing that code suggestions go on Github, while other comments go on the forum.

I was just thinking about this, if we want to stick with this logic then we need to move all other code snippets/examples in User/Developer guides to Gists, too. Keep things consistent.

What other ones are there? Core code, for example, is already on Github.

I’m referring to example snippets inside actual guides. For example, all the code examples in this guide using syntax highlighter:

As mentioned, I was initially using gist for CC code snippets. I used a WP plugin to embed them on the page. Pretty sure it was this one. https://en-au.wordpress.org/plugins/gist-github-shortcode/

1 Like

I agree with @timkaye that comments on DOC should not be enabled nor back ported. Anyone who has ever studied those comments in depth knows that too many of those actually are not only wrong but even dangerous at times.

It also adds a whole lot of work we do not have the *power for.
Unless of course someone is willing to take on the work of reviewing and vetting each comment, and with vetting I mean vet, not just spell check. This means to test each code comment, make sure it doesn’t propose crappy unsafe approaches or plain wrong things. Then, as soon a release is made, each of those comments may become outdated, and would need a revision.

IMO, and as mentioned during the extensive discussion of implementing DOC, we should learn from this and not implement it


About the code snippets repo part, I am hugely in favour of doing things centrally and that means keep it in DOCs, not using GIT.
My only concern about that I expressed before already: we take on a certain responsibility when we publish code snippets on “our” sites. This is different than documenting core code or best practices or example code in a DEV Doc. Those are A) vetted during development for core code, B) very carefully crafted when writing up DEV Doc.

If we want user input on the code snippets, then I say we just put a link to the gist or repo in GIT with a big fat disclaimer about “this is user shared content, use at your own risk”, and that’s it.

However I do not see why we would want direct user input.
The actual benefit of a dedicated and curated snippet repo is IMO only granted if the code gets reviewed, and that directly require that only a few people can post it.

Everyone could suggest their snips, in any way they want, and they can even get attribution in the snip if it gets posted. This would make this repo unique, due to its degree of vetting and so on.
This is similar to having comments enabled that get reviewed, but it is central, and not spread over 8k posts.

Otherwise, it is just another SO, where basically all kind of weird stuff will get posted.

Anyway - to proceed on this, all we need is to decide. If we do it on the DOC site, I am happy to add CPT or similar, it takes perhaps an hour to do so.

@anon66243189 you can have a form somewhere for snip submissions, and have someone carefully select and vet the ones that make it to the spotlight.
Then publish them as a CPT.
I agree that if we want to offer a quality collection we need to vet the content and avoid everybody and the cat polluting the collection.

A post was split to a new topic: Snippet Repo Location Vote

You didn’t allow for other options. I don’t like any of those, because it’s more work for a contributor who has to want to do docs and code.
I prefer the way WP does it, where it’s feedback on the code reference, and it’s obvious that it’s user-submitted.
And, anything that is widely needed as a snippet should be incorporated into core.

I’m not really feeling any of those options either. I voted for #3 as it’s the one I like least worst. :slight_smile: They all seem overly complicated. It seems like “too much input” has led to overthinking the whole thing.

I’d take a much simpler approach: use a CPT on the docs site and open the comments there for input. It would also require a simple public-facing submission form (for adding new snips). And users would be required to have a forum account so SSO could be used for login. The submission form (and comments form) would be behind the SSO. For existing snips, user’s would add comments to those snips if they wanted to get them updated/changed. The comments would then be moderated in place rather than directly appearing with the snippet. After being tested/vetted, the snip would be added/updated and the original comment would either remain hidden or be deleted. I wouldn’t even think about versioning as this just complicates it for all involved and, in terms of codesnips, it serves little purpose.

I agree that it seems better than the options proposed above. There, it’s obvious that “the main part” of the docs posts are the project-recommended parts…and the user comments are the use-at-your-own-risk part. People who consume WP docs are already very familiar with this practice.

I differ here. This assumes too much about the needs of every user and can lead to core bloat.

I’ll cover both of your responses @joyously and @Code_Potent and the reasoning for not including the comments.

At least 3 people mentioned/agreed not to open the comments up. Also, the SSO part was something I mentioned, but that also poses several problems - users have to be created in the CP database, so even though it’s SSO they still exist on those sites. So we could end up with thousands of users in the docs database, when CP grows to that point. If docs site is compromised, we would have to deal with breach reporting to comply with GDPR if there are so many users. There’s also requests for data to be deleted/edited. Keeping things simple and future-proofing it, will help us avoid WP headaches.

So far, the leading option is 4. One of the reasons I kind of like it, and people might disagree, is that we can show snippets in the CP admin once directory is integrated and allow users to search for them. They could also be surfaced along with plugin searches. For example, if someone searches for “shortcodes” plugin we could show a snippet on how to create a shortcode. User could choose to create their own shortcode and follow instructions.

The submission process is more flexible. I listed a simple forum-based option because that’s a safe way to go, just like our petitions. One option that might be available to us is integrating forum with the docs site to display forum threads as comments. Exactly what we did with comments on the main blog. This would prevent SSO/comments issue described above, and still give us comments if we wanted to.

Lastly, I had to push this forward because there hasn’t been any activity on this in 4 days. One big problem we had in the past, especially with committees, is that not much ever got through to actually getting done. We need to change that and get things done :slightly_smiling_face:

Yeah, I’ve followed the discussions and understand the various reasonings…I just think of it differently. :wink:

I see no problem with having thousands of users in a database. And, whether they are in the forum database or the docs database, the data is subject to the same risks and reporting requirements.

If I’m searching for a plugin, I don’t want DIY tutorials coming up in the results. This muddies the results, particularly for users for whom codesnips are “over their head” (for lack of a better term.) I suppose if it was filterable, it wouldn’t be so bad…it just seems a bit cobbled-on and without much thought to simple “lay” users of the directory.

Absolutely agree. That’s why I mostly worked with CP solo and just released things rather than kill them with discussion. :wink: I’m 100% in support of removing roadblocks and moving forward – like Wade did with the plugin directory after it got stymied for 2 years. :slight_smile:

They would be in both databases. And as we know, WP/CP gets attacked often. So it does increase risk. For all I know, in the future, we can add comments to snippets that might be hosted by the directory. So anything is possible in the future.

This is completely my idea and isn’t related to option 4 at this point. That’s just me thinking out loud about what’s possible.

Mostly, I’m glad to see action on it. Props to all for putting in the elbow grease to move it forward.

1 Like

@viktor if option 4 is making it, we can simply make the snippet submission be the same as plugin submission requirements.
This way, we don’t need to clutter forum and snips submitted get properly prepared by their authors because they know there will be a hard vetting process just like for plugins.

2 Likes

That’s a good point, I didn’t even think about that.

1 Like

The poll closed. 66.67% chose option 4, which is hosting snippets in the directory alongside plugins and themes.

1 Like

Let’s draft out what it should look like (ie. submission flow, approval, etc) and then we can add it to the list of work to be done for the directory.

@Devrealm_Guy and I are currently working on some of the admin side things, but we should be able to squeeze it in. I also am hoping to get the directory open sourced so we can get more help in some areas, but no ETA on that yet.

I was thinking starting a new, planning thread might be a good idea since this thread served its purpose.

Edit: I have created a planning thread “Snippet Repository planning” and will mark this thread to be closed.

1 Like

This topic was automatically closed after 33 hours. New replies are no longer allowed.