search

wpsharks / wp-kb-articles

KB Articles for WordPress; adds a new Custom Post Type.
http://wpkbarticles.com/
2 stars 1 forks source link

Feature Request: Integrate the GitHub Issue to KB Article Tool #91

Open raamdev opened 9 years ago

raamdev commented 9 years ago

The current GitHub Issue to KB Article tool could be integrated into the Pro version of the WP KB Articles plugin, so that site owners could simply load a specific URL on their domain to access the interface.

Or even better, there could be an additional interface inside WordPress provided by the WP KB Articles plugin that lets users access the functionality provided by the GitHub Issue to KB Article tool, maybe a new menu option called "Import GitHub Issue" that appears when the GitHub Integration is enabled.

I was thinking we might maintain the API separately and have the plugin connect to the API, e.g., hosted on wpkbarticles.com, however after thinking about that a bit I realized that site owners wouldn't like the idea of us getting their Personal GitHub Token!

This would be a GREAT value-add for the Pro version of the plugin and when we start talking about the plugin and marketing it, it would be nice to be able to demonstrate a workflow that includes all the tools necessary inside the WP KB Articles plugin itself ("All you need is WP KB Articles Pro + GitHub!").

What Actions Need To Occur Here?

raamdev commented 9 years ago

If integrated with the plugin, it would be cool to allow site owners to define the GitHub Repo directory structure used when importing a GitHub Issue and writing a new Markdown file. For example, they could use tags to define the directory structure, like /%%category%%/%%year%%/%%markdown-file%%.md etc.

While I'm on this train of thought, I'm thinking about how much we can do to reduce the amount of "setup" work required by a site owner to start using the GitHub Integration. It would be nice if all a site owner had to do was create a GitHub Repo, provide that new GitHub repo name and a personal access token to the WP KB Articles plugin, and then start creating new GitHub Issues in the repo and then importing them to WP KB Articles--no need to create a set of directories in the repo that matches the categories you're planning to use, etc. All of that could be done using what's defined in the YAML config.

jaswrks commented 9 years ago

@raamdev writes...

tags to define the directory structure, like /%%category%%/%%year%%/%%markdown-file%%.md etc.

Cool. I love this idea. A configurable option for this would also give us a platform there to discuss best practices associated with this structure and offer a default value based on our recomendations.

jaswrks commented 9 years ago

@raamdev writes...

I was thinking we might maintain the API separately and have the plugin connect to the API, e.g., hosted on wpkbarticles.com, however after thinking about that a bit I realized that site owners wouldn't like the idea of us getting their Personal GitHub Token!

There is a bell ringing in my head that's telling me WPKBA could eventually become a SaaS model, where we provide an improved KB-centric interface to GitHub. However, it's not an exact fit for this in my view, and its current home inside WordPress seems as good a fit as any—at least for the moment. Still, my mind keeps wandering into the SaaS world with this plugin. I just can't picture it all yet.

@raamdev writes...

This would be a GREAT value-add for the Pro version of the plugin and when we start talking about the plugin and marketing it, it would be nice to be able to demonstrate a workflow that includes all the tools necessary inside the WP KB Articles plugin itself ("All you need is WP KB Articles Pro + GitHub!").

Cool! I was thinking that an interface for the "GitHub Issue to KBA Converter" might be unnecessary. I think this tool could become a part of the GitHub interaction, instead of needing to switch over to another UI.

Do you have any thoughts on the following?

Instead of building a UI for this, what about connecting this converter to one of the more recent additions in WPKBA, it's GitHub Webhook. With this, you could simply Tag an Issue on GitHub (e.g., publish-master) and that would trigger the converter automatically; but only if the tag was added by a collaborator with permission to do so.

Given the way GitHub's interface works, this could even be made to feel like it is built right into the GitHub experience; i.e., you add the Tag, and suddenly the Issue is closed. A quick test shows that you'd need to refresh the Issue to see all of the changes that the converter makes. That still seems easier than moving from one UI to another.

raamdev commented 9 years ago

what about connecting this converter to one of the more recent additions in WPKBA, it's GitHub Webhook. With this, you could simply Tag an Issue on GitHub (e.g., publish-master) and that would trigger the converter automatically; but only if the tag was added by a collaborator with permission to do so.

Whoa. That's even more amazing.

To take this one step further, we could use such functionality to actually control the Post Status on the WordPress side as well. If the GitHub Issue is labeled wp-published, then post gets marked as Published by WordPress. If it's labeled wp-draft or wp-pending-review, its status changes appropriately.

That would make the entire GitHub → WordPress KB experience seamless. Right now the only reason I visit the WordPress side of things is to preview a KB Article and to mark a KB Article as Published. That's it! If I have a link to preview the KB Article in the GitHub Issue and I can simply label the GitHub Issue as wp-published to Publish it, then I don't even need to visit the WordPress Dashboard at all.

raamdev commented 9 years ago

If the GitHub Issue is labeled wp-published, then post gets marked as Published by WordPress. If it's labeled wp-draft or wp-pending-review, its status changes appropriately.

I'm not sure how this would work with regards to existing YAML config inside the associated Markdown file. Maybe the GitHub Issue labeling to change WP Post Status only works if the YAML config does not contain a status: key. If it does contain a status: key, then that overrides the GitHub Issue labeling.

raamdev commented 9 years ago

you could simply Tag an Issue on GitHub (e.g., publish-master)

I would definitely make such a label configurable from inside the WP KB Articles plugin options, as different people may have different preferences for what's used there.

I assume the -master part is referencing the GitHub branch that should be used when publishing a Markdown file. If so, that's awesome! :-)

jaswrks commented 9 years ago

Great suggestions! Thanks.

I added a list of actions (↑ above) that need to occur.

@raamdev writes...

I assume the -master part is referencing the GitHub branch that should be used when publishing a Markdown file. If so, that's awesome! :-)

Correct.

raamdev commented 9 years ago

Adding another checklist item. ↑

  • Ensure proper handling of YAML Markup that includes : [ (e.g., title: [s2Member-Profile /] Shortcode, either with an informative error message indicating the problem, or by handling the issue so it's not a problem (preferable).