Documentation #2131
closedHosting partner handbook
Added by Boone Gorges about 12 years ago. Updated almost 10 years ago.
0%
Description
As we work more and more with orgs/publications like JITP and MESTC, who do their own WP development off-site but are then hosted on the Commons, it would be helpful to codify and make public some guidelines and best practices. I'm thinking that we might think of this "partner handbook" (better name ideas welcome) as a living document, which resides maybe or the Codex or dev.commons.gc.cuny.edu, and evolves over time as we hone the partnering process.
Off the top of my head, here's some content I think should be in there:
- Information about our release schedule (1st, 11th, 21st of each month), and, in addition, a turnaround time for CAC team review. So, for example, we might say that you have to have stuff to us by 4 days before a release in order for it to be included. Or whatever.
- Plugin policy. We have a strong preference that sites use the plugins we already have installed, but we'll consider reasonable requests for plugins to be added, pending review by our dev team.
- Themes. Custom themes should pass the Theme Check http://wordpress.org/extend/plugins/theme-check/ with no high-level errors. Theme code is reviewable by CAC team. No SQL queries or other funny business in themes.
- Communication. Should use Redmine for non-sensitive communication.
- Sharing files. Zips (Redmine attachments, email, etc) are fine for now. Down the road it would be cool to come up with a system where partners could dev on Github and we could include their stuff as submodules, and updating would mean updating the rev number of that submodule on our install. (No need to include this bit until we've figured it out.)
- Other stuff?
==
As for the technical aspects, maybe this should ultimately live in a hardcoded page template, so that it's under version control. For drafting, we could use a wiki page somewhere, or a BuddyPress Docs page, or whatever.
Dom, I'm assigning this to you for now, as you've been handling this kind of task for the last dev cycle or two. However, I'll be happy to chip in with some of the writing and editing once some of the CBox deadlines loosen up a little. This is a pretty low priority item.
Updated by Matt Gold about 12 years ago
Let's also include information on requesting plugins/themes -- such as this form (which needs revision). If we post this guide on a blog, we can include the form right there on it, too.
Updated by Dominic Giglio about 12 years ago
Boone,
Are there already sources of information spread across the Commons with tips/best practices regarding working with partners (codex, github, group docs, etc)? I don't want to double up on effort if there is already some info that I can start pulling together.
I think I'm going to start a doc in the project planning group for now. This will allow everyone to chime in on the content and voice their opinion as to where the info should ultimately be hosted.
Updated by Boone Gorges about 12 years ago
Are there already sources of information spread across the Commons
Nothing jumps to mind. Any existing information is in the emails that we've exchanged with each other.
I think I'm going to start a doc in the project planning group for now. This will allow everyone to chime in on the content and voice their opinion as to where the info should ultimately be hosted.
Excellent idea.
Updated by Dominic Giglio about 12 years ago
Boone,
I've started a draft as a dev team group doc:
As far as hosting the info as a page on the Commons, I could code up something similar to the twitter page I created. A single template where we could host the info plus integrated forms for uploading plugin request, theme requests and theme/plugin files for releases. It could be something like commons.gc.cuny.edu/partners. Just a thought, not sure if that would simplify or complicate things.
Updated by Matt Gold about 12 years ago
Thansk for your work, Dom. I'd suggest integrating this into the dev blog, though you're right that we could of course build out a new page/section of the parent site.
Updated by Dominic Giglio about 12 years ago
I thought about the dev blog first. But then I started to worry that the info might get slowly buried by future posts about releases and new features.
It seems to me that this info may be important enough to warrant it's own top level page on the commons. That way any third party contributors have an easy to remember URL where they can always get the latest info regarding how we expect to receive info and communicate about future releases.
Plus if we want to integrate forms that allow third party developers to submit requests for plugins and themes and upload their custom source code, I think it would work better on a more static template page. That's just an idea though, we may not want to allow uploading of content directly through the site.
Updated by Boone Gorges about 12 years ago
But then I started to worry that the info might get slowly buried by future posts about releases and new features.
Make it a static page, rather than a blog post.
It actually strikes me that the correct place for this is the Codex.
Updated by Dominic Giglio about 12 years ago
Isn't the Codex really just MediaWiki? Aren't we getting rid of (or moving away from) MediaWiki?
Updated by Matt Gold about 12 years ago
Look, too, at the Technical FAQ Boone set up on the dev blog - http://dev.commons.gc.cuny.edu/technical-faq/
Updated by Boone Gorges about 12 years ago
Isn't the Codex really just MediaWiki? Aren't we getting rid of (or moving away from) MediaWiki?
It's MW being pulled into a Commons blog. We may move away from MW in the distant future, but that's not a reason to avoid using it now, for this purpose.
What I meant is that the Codex seems like it's where this belongs in terms of where someone would go looking for this piece of info. I want it to be findable, but I don't necessarily want to trumpet from the mountaintop that we do this kind of thing, as I don't want us to be in the hosting business.
The dev site would also be fine, but that's intended for an external audience. The Codex is meant for Commons members, which seems more appropriate for this.
Updated by Dominic Giglio about 12 years ago
Matt,
That's great info that should be incorporated into this new handbook. I will make sure that happens.
Boone,
That does make a lot of sense. :-) Plus, being on the codex it is FAR easier to keep updated and current. This is probably the way we should go with this.
Updated by Boone Gorges about 12 years ago
Plus, being on the codex it is FAR easier to keep updated and current. This is probably the way we should go with this.
Cool. If we need a form or something like that, we can create a page (which is otherwise hidden from the nav) and just link to it.
Updated by Dominic Giglio about 11 years ago
Boone,
This is an update related to the reply I sent on the Community Planning group regarding plugin updates.
I've created a new spreadsheet similar to the Theme Audit spreadsheet that we can temporarily use to get an overview of the status of our pending plugin updates. I think it might help us (me) better organize which plugins to update and on which dates they need to be updated. I've shared it to whomever has the link just like the Theme Audit spreadsheet:
https://docs.google.com/spreadsheet/ccc?key=0Ap2ItX5DDHPddDExZU1QRGZqalhrM3lWdTExdFI4Y3c&usp=sharing
While I was putting it together I thought I might be able to whip up a really nice plugin that will automatically organize all this info for us. Remember all the work I did getting the table layout working for the email plugin that was completely unnecessary? Well, I think I might be able to take that code and create a plugin that will parse all our pending updates into separate tables for major and minor updates. That way we can see exactly what needs to be updated anytime we want in the Network Admin. I could even blacklist the never update plugins so we wouldn't have to weed through ones we don't ever want updated.
Let me know what you think about the new spreadsheet and the plugin idea. I don't want to start working on it if you don't think it's a good idea. It would be just another waste of time.
Updated by Boone Gorges about 11 years ago
- Status changed from New to Assigned
Hi Dom -
Thanks for resurrecting this ticket. I didn't have this ticket explicitly in mind when I was writing http://dev.commons.gc.cuny.edu/release-schedule-and-procedures/ - my goal was to clarify one specific piece of workflow ("major plugin" updates) - not to create a comprehensive set of guidelines for our hosting partners. Though, in retrospect, there is obviously much overlap, and perhaps the info there would be better included in such a comprehensive handbook.
The plugin-update-plugin is a cool idea. Having done one cycle of the major plugin update stuff, I can say that it does add a bunch of manual work for me - both on the 5th (when I have to compile the list) and on the 21st (when I have to run the updates). If you can come up with a tool that will automate some or all of this manual work, that'd be great. I can imagine something like the following:
- A tool that lets you see, at any given time, which plugins have a major update upcoming
- That tool would also store, on the 5th of each month, the major update info, for reference on the 21st
- Some sort of integration into the Updates screen (like, perhaps, a piece of red or green text next to each version number), that'll let me know on the 21st whether the plugin is green-lighted to be updated, and if not, what the most recent greenlighted version is. Then, I can manually select the plugins by using the checkboxes.
Is this the kind of thing you have in mind?
As for the handbook and its format, I think that the document you've started at http://commons.gc.cuny.edu/groups/cac-community-team-project-planning/docs/partner-handbook-rough-draft is actually pretty good as a starting place. It probably makes sense to merge in some of the info from the release workflow document, but I think that the general format of what you've got there is pretty good. What would you like from me in order to help you move forward on that project?
Updated by Dominic Giglio about 11 years ago
- Target version changed from Not tracked to Future release
I'm bumping this to Future Release since we're back on it again and it's a little more pressing now that we've actually experienced a plugin related prblem with an external developer (Events Manager / Kimon).
What I had in mind is very similar to what you describe. At first I thought a plugin that adds some CAC specific functionality to the current update admin page would be nice, but the more I thought about and read about your proposed update workflow the more I thought we might need a completely separate customized admin screen to better automate this new process. That's what made me think of the email-updates plugin I worked on with admin tables and other related functionality.
As you already know, I've also worked on plugin updates during different release cycles and even without the new 5th/21st system it was very difficult to keep track of blacklisted plugins and then get all the others updated properly hoping the whole time it wasn't going to break one or more sites. I'm going to get started on something simple, a proof of concept and initial structure that you and I (and maybe even Ray) can have a look at to decide how best to move it forward. Ideally, I'd like to create a one click solution that can be visited on the 5th and again on the 21st making the whole process brainless, but that only works one step at a time.
I'll get going on this and report back when I have news. For now I think the answer to your last question is: what I need now is a decision between the two of us as to where we ultimately think this handbook should live. There was discussion above about putting it on the Codex. Which is still a good idea I think. It would allow cooperative editing which should speed the whole process up a little. I've never done anything on the Codex so maybe I'll reach out to Scott and ask him for a little intro like he'd give a Commons user writing in from a support request. It may also be a good idea to get it on the Codex since I'm also assigned the MediaWiki upgrade which I looked into first so long ago that I don't even remember all the pieces of technology involved in making it run. Other than where we want this to ultimately live I think the info in the current group doc and the new pages on the dev blog outline everything needed for a first version. Where we want it to live is probably the most pressing question right now.
Updated by Boone Gorges about 11 years ago
This all sounds great. Thanks, Dom.
what I need now is a decision between the two of us as to where we ultimately think this handbook should live
Unless someone feels strongly otherwise, let's go with the Codex. Please feel free to reach out directly to Scott, or to use the space here (he's a watcher on this ticket) to discuss details.
Don't hesitate to ping me when you need specific feedback on some aspect of the project. Thanks!
Updated by Dominic Giglio about 11 years ago
Boone,
I've added the first version of our new CAC Plugin Updates plugin to 1.5.x. It doesn't do anything yet so I didn't think there would be any problem adding it directly to the version that will be deployed tomorrow. I've added a note to ACTION_REQUIRED reminding you to Network Enable it.
I think what we need to do now is decide what functionality we want to enable to help us better handle this new plugin update cycle we're defining. Currently the plugin only lists updates available so it isn't any more helpful than the core plugins admin page. I've added a simple blacklist array to keep never-updated plugins out of site. We could discuss expanding that into a setting that is stored in the database so we can edit that list in realtime.
I believe the next feature we should discuss is the actual display of plugins by version. I see two potential implementations right now:
1.) I could add text areas below the table to output the content of the blog posts we publish listing plugins that will be updated on a specific date.
2.) I could separate the interface into two separate tables so that major updates are separate from minor updates.
Let me know what you think so far, and what you would like to see added to ease this entire process.
Updated by Boone Gorges about 11 years ago
Hi Dom. Thanks for your work on this so far.
1.) I could add text areas below the table to output the content of the blog posts we publish listing plugins that will be updated on a specific date.
2.) I could separate the interface into two separate tables so that major updates are separate from minor updates.
Both of these sound great. (1) is not super important, but I think it'd be pretty easy to implement, so let's go for it. As for (2), I don't think it's so important to have separate interfaces, but there should definitely be some sort of indicator. Even just another column on the table - something like "Update Type", maybe with different colors for Major and Minor updates. In either case, it'd be nice to have an easy way to check all plugins of a given update type.
Then, of course, the bulk updater will actually have to be implemented (process_bulk_action()). I'm hopeful you can just pull this logic out of WP's core table.
For further development, what'd be really helpful is the following:
(3) Create some mechanism for saving (manually or otherwise) the available updates of a given type on a particular day. Eg, a button in the interface that says "Major update snapshot" or something like that; on the 5th, someone could click that button, and information about the currently available major updates would be saved. Then that info could perhaps be displayed in another table column.
(4) Some automation for this stuff. Ie, something that detects that it's the 5th, and automatically takes the snapshot.
But I think (3) and (4) should come after (1) and (2), since they're somewhat dependent anyway, and since (1) and (2) will save a bunch of work by themselves if implemented.
Updated by Matt Gold almost 11 years ago
Hi Guys -- where do we stand on this? I have a new person who is interested in uploading theme files for a project and it would be useful to point to some resources . . .
Updated by Dominic Giglio almost 11 years ago
Right now I believe the only two sources of official info regarding our procedures and updates are the dev blog posts:
http://dev.commons.gc.cuny.edu/2013/09/05/new-release-schedule-and-procedures-document-available/
http://dev.commons.gc.cuny.edu/release-schedule-and-procedures/
We do not yet have an authoritative guide for third party theme developers. I think Scott might have something on the Codex to get this new person moving in the right direction but he will have to speak to that.
Updated by Matt Gold almost 11 years ago
Thanks, Dom. Are you still planning on a handbook of some kind for hosting partners?
Updated by Boone Gorges almost 11 years ago
The main additional point for the purposes of theme development is to run the theme against the official WP theme check plugin: http://wordpress.org/plugins/theme-check/ Make sure that any of the critical errors are fixed.
Updated by Matt Gold almost 11 years ago
Given that this ticket now hosts a long conversation, it might be useful to start a doc here on redmine or in our cac group on the Commons to detail the prospective contents of this handbook.
Updated by Dominic Giglio almost 11 years ago
One of the updates above discusses setting up the handbook on the codex and also discusses a document in our dev group I believe. I think it would be best as a doc in the dev group. That would give everyone access in an env they're familiar with. I think I have a doc already somewhere. I will find it and post the link as an update here.
Updated by Boone Gorges about 10 years ago
- Assignee changed from Dominic Giglio to Boone Gorges
Hi everyone - I've just posted a draft of the handbook text that I've created so far: http://dev.commons.gc.cuny.edu/?page_id=1019&preview=true (you need to be logged in to see it). Feedback/edits are welcome.
My tentative plan is to keep it as a page on dev.commons.gc.cuny.edu, but it may be more appropriate on the Codex. Scott, your thoughts would be helpful here.
Updated by Matt Gold about 10 years ago
Awesome, Boone -- this looks great. One small thing to add: maybe we can/should provide a few examples of domain mapped sites on the Commons?
Updated by Matt Gold almost 10 years ago
Hi Boone, I think that this is ready to publish unless you see a need for further feedback.
Updated by Boone Gorges almost 10 years ago
Thanks, Matt.
(a) Do you want there to be examples of mapped domains? If so, which?
(b) Is it OK with you (and Scott) to put this on dev.commons.gc.cuny.edu? If not, where would you like it?
Updated by Matt Gold almost 10 years ago
Thanks, Boone. Here are some examples of mapped domains we can point to:
http://preludenyc.org/
http://asianamericanyc.hunter.cuny.edu
http://chaserobinson.net/
http://murphyinstituteblog.org
http://keithmiyake.info/
http://globalization.gc.cuny.edu/
I'd say that we should publish this on the Dev blog for now. At a later point, we can consider making it a separate site. Scott should also add links from the Codex to the post.
Thank you!
Updated by Boone Gorges almost 10 years ago
- Category name set to Documentation
- Status changed from Assigned to Resolved
- Target version changed from Future release to Not tracked
The page has been published: http://dev.commons.gc.cuny.edu/hosting-partner-handbook/
Updated by Matt Gold almost 10 years ago
Awesome - thanks, Boone. Sending an email to point someone to this today.