Snippet Repository planning

Based on the feedback and the poll, the snippet repository will be housed in the directory alongside plugins and themes. Now is the time to figure out all the details.

Submission and review process

What would be the best way to receive submissions? One possible way:

  1. Create a form that an authenticated user can submit, which includes an ACE editor for the snippet.
  2. In the admin, there would be a queue of pending submissions.
  3. A reviewer would review the snippet.
  4. If rejected, an email would be sent to the submitter with the reviewer’s comment.
  5. If approved, the snippet would need to be published on GitHub and then published in the snippet repository.
  6. Each snippet should have an option to submit feedback or complaint, so users can report issues or add feedback. This can be reviewed privately and acted on if necessary.

Note: We should avoid requiring GitHub/Gist for submissions to keep the barrier to entry low.

Publishing on GitHub

Gists would need to be published under the ClassicPress account since they are not tied to repos. There are 2 questions here:

  1. Do we create a separate account to manage Gists?
  2. Can Gist creation process be automated using GitHub CLI (gh gist create) so when the reviewer hits “Publish” the directory creates a Gist and publishes snippet in the directory?

Snippet management

The admin side would need some basic management settings like modifying snippet details, unpublishing a snippet, deleting a snippet, etc.

Let’s figure this out.

3 Likes

This makes the most sense to me. Ideally, the directory will pull in all public gists. Any private gists are not pulled into the directory. Then, to publish/unpublish a codesnip, you simply have to change the public/private status at GitHub. This would remove a step in the submission process, and also remove a step in the unpublishing process. Likewise, deleting a gist at GitHub would delete it from the directory. In terms of deletion, I’d probably fall on the side of unpublishing rather than deleting.

Creating a new account isn’t really necessary, and it adds to the overall management of the project. Using the existing ClassicPress-centric account makes the most sense.

If users aren’t required to have a GitHub account, the form can’t be hosted there. Using the forum would be “easy” but, it disconnects the feedback from the directory and strings the data out across several platforms. Personally, I’d avoid using forum-based feedback – too much discussion from too many people has derailed too many activities in the space already. Along these lines, I’d add a simple comment form to each gist (on the directory) which doesn’t (or does) require login to submit – and then those comments would only be admin-viewable, for review or further action.

2 Likes

Thanks for the feedback. If we can do everything programmatically via GitHub CLI that would be ideal. But that does add more work, which means it would take longer to complete. In the meantime, a manual process probably would be needed.

Doing everything via CLI wouldn’t require a separate account. We would only need a separate GitHub account if we’re publishing Gists manually, so the main account can remain locked up.

A forum is an easy option, definitely. However, to clarify my suggestion, I was thinking of something similar to the commenting system in ClassicPress. A simple form that’s part of the directory and there would be a Feedback queue for someone to review. Feedback would not be publicly available. Only authenticated users (which uses forum authentication) would be able to submit feedback/complaints for the snippets to prevent spam.

3 Likes

I am torn on the forums, as it may lead to a lot of new threads created in short periods of time, but I do think leveraging the commenting system similar to the main site would be good. I don’t quite know how I will do that within the directory but I am open to it and think it is a good idea.

We could maybe create only x threads per hour or whatever to help avoid flooding the latest.

1 Like

I would not recommend creating threads for each snippet or displaying whole conversations on each snippet’s page. I don’t think that’s necessary. If we need to discuss a snippet, a thread can be manually created and no need to link it to the snippet’s page. Maybe a simple hyperlink would be fine.

For the feedback/complaint form, what I was thinking about is something you can see in Helpful plugin. You’ve seen it on many documentation sites.

This would only be available to logged-in users. Visitors would be asked to log in. Feedback/complaints would be kept private unless a forum discussion is warranted.

1 Like

Option 4: Code snippets will be posted in the directory along with plugins and themes. Code snippets will be hosted by GitHub as Gists. So the directory will be searchable for plugins, themes, and code snippets. The submission process will be on the forum, as described in option 1.

Just remove the bolded part.
There’s no need for forum pollution. We do not do that with plugins either.
The process is:

  • create plugin
  • upload to git
  • submit for review
  • gets accepted
  • publish on our directory ((in form of a post, then link to the actual code!)

The same should be possible for Code snippets.

If someone has concerns on using a Gist/Git, then he/she should likely also not be writing code snippets for other people. This is an acceptable entry point. We are not talking simple doc. We are talking real code.

Implementing a whole form with code editor and such is dangerous and requires a lot of work.
Instead, if we do it exactly like we handle plugins and themes we have no additional work.

I think this tiny change lifts off a lot of complexion without destroying the vote results.

3 Likes

Started the Snippet Repo today, will follow the same flow as plugins for simplicity for now :+1:

4 Likes

Thanks for an update. Great news.

2 Likes