Project

General

Profile

Outreach #1998

Prepare and release CAC Featured Content rewrite

Added by Boone Gorges about 7 years ago. Updated almost 7 years ago.

Status:
Resolved
Priority name:
Normal
Category name:
-
Target version:
Start date:
2012-07-18
Due date:
% Done:

100%

Estimated time:

Description

Now that the CAC Featured Content plugin rewrite is about done, let's get it out there to the public. Here's a rundown of what has to happen.

- Create a readme.txt. The wordpress.org plugin repository requires this. Make sure that cuny-academic-commons is one of the names listed on the Contributors line

- Adjust the plugin's file structure a bit. The plugin is BuddyPress-dependent, so it should have a loader file that uses this technique to load only when BP is present: http://codex.buddypress.org/plugin-development/checking-buddypress-is-active/. Another complication is that users of the old version of the plugin will find the plugin deactivated if the main plugin file (the one with the plugin header data) has changed its name. Currently, the loader file is cac-featured-content/cac-featured-content.php; it'll probably cause a bit less headache with upgrades if you keep that filename for the loader file, and then move your main plugin logic into a separate file.

- Decide how you want to manage ongoing development. We've been handling the rewrite in the private CAC repo, but it should be moved elsewhere. I have a github repo for the plugin, which you're welcome to have if you want, though you're welcome to do something else if you'd prefer. You'll also want to decide on the "official" way that you'll field public support requests for the plugin (you should support it at least for the major issues, under the aegis of CUNY) - Github issues, the wordpress.org plugin forums, the buddypress.org plugin forums, something else, or some combination of the above. These details should be laid out in the readme file, as well as in the release post, so that users know where to go for updates or where to submit patches and issues.

- Release on wordpress.org svn. Dom, have you done this before? If not, I'll help to give you instructions. Please give me your wordpress.org username, and I'll add you as a committer for the plugin.

- Write a release post for http://dev.commons.gc.cuny.edu. A few paragraphs on the purpose of the plugin, the purpose of the rewrite, and a rundown of the features, maybe a couple of screenshots if you feel industrious :) This post should only go live after the release is finished, and you've verified that the plugin is live in the wp.org repo.

History

#1 Updated by Boone Gorges about 7 years ago

Forgot to include a link to the readme.txt format standard: https://wordpress.org/extend/plugins/about/readme.txt

#2 Updated by Matt Gold about 7 years ago

I agree that we should support the plugin, as doing so is good for the code and ultimately good for us. But we may have to set reasonable limits on support if demand is high. Dom, please keep us in the loop on time allocations in this regard. Many thanks.

#3 Updated by Dominic Giglio about 7 years ago

I just want to address a few of your points, I will be back to discuss the others once I've gotten #1151 (MediaWiki) and #1386 (profile fields) out of the way.

I always planned on the code going back into its repo on Github. That's why I bumped its version to 0.9. By the time I add the remaining functionality from this ticket and the others, we might as well bump it again to 1.0.0. What do you think about moving its repo to the cuny-academic-commons Github account? Is that for Cbox related repos only?

I don't mind supporting it at all. I will think about the support options while writing the README.

The only knowledge I have regarding releasing a plugin to the svn repo comes from your posts on git-svn that I just read. We can discuss the specifics when the time comes. I have two entries in my password manager for WordPress: one for the dot org forums and one for trac, both usernames are 'humanshell'.

#4 Updated by Boone Gorges about 7 years ago

What do you think about moving its repo to the cuny-academic-commons Github account? Is that for Cbox related repos only?

That's fine with me. It's been moved, and you now have admin access. Good idea about v1.0 as well.

It looks like the plugin has been delisted from the plugin repo (probably because it uses timthumb), so I can't add you as an svn committer at the moment. I've pinged the powers that be to lift the ban.

#5 Updated by Boone Gorges about 7 years ago

Dom - FYI, the plugin is relisted, and I've made you a committer. https://wordpress.org/extend/plugins/cac-featured-content/

#6 Updated by Dominic Giglio about 7 years ago

Cool, will get on these remaining issues as soon as I can.

#7 Updated by Dominic Giglio almost 7 years ago

Boone,

I've created a new README.md for the Github repo and added a WordPress.org readme.txt version.

Let me know what you think.

https://github.com/castiron/cac/commits/featured-content

#8 Updated by Boone Gorges almost 7 years ago

Hi Dom,

Thanks so much for your work on these readmes. They generally look great. A couple comments.

- As it stands, the plugin is BuddyPress dependent - you'll fatal errors if you try using it without BP. You say "is a BuddyPress plugin at its core" but you may want to choose a phrase that makes the dependency a bit clearer. (Also, you've got to change the plugin structure to reflect the BP-dependency, as discussed in my original ticket description - don't forget this, because people do not read readmes like they should :) In the future we can talk about making BP support a progressive enhancement, using some strategically-placed do_actions(), but for now it is required.)
- Screenshots are very nice, if you don't mind taking one or two. Maybe one of the admin panel, and one of the front end. Good screenshots will improve download counts!
- You may want to add a note about where you can get support, send feedback, submit patches.

#9 Updated by Boone Gorges almost 7 years ago

Oops, one more thing about the readme:

- This release breaks backward compatibility in a couple ways. From a dev standpoint, if anyone was using any of the (few) filters in the old version, they'll probably break in this release. I highly doubt anyone was, so don't worry too much about this. From a user standpoint, any existing CAC Featured Content widgets will lose their content when the plugin is updated. In an ideal world, we would try to migrate this content gracefully, but to be honest, it's a lot of busy work to write these kinds of migrations, and it only takes about thirty seconds for the admin to repopulate the widget. In any case, you'll want to feature a note about repopulating the widget.

Related, you might find it useful to add an upgrade notice to readme.txt, so that users will see this bit about widget repopulation before upgrading the plugin. See the Upgrade Notices section of http://wp.smashingmagazine.com/2011/11/23/improve-wordpress-plugins-readme-txt/

#10 Updated by Dominic Giglio almost 7 years ago

OK Boone - this update will prob get kinda long, so bare with me...

I'm going to attempt to summarize the current state of the CFCW plugin here, because I believe it's about ready to be released. I will post brief updates to both #2026 and #1982 that reference this update once I'm done here.

Localization:
  • I've moved $widget array initialization into the constructor per your suggestion and it works perfectly.
  • I used poedit to generate a default.po file. I left it named default.po because that's what the post you linked to called it and that was the default name in poedit. If you want me to change that to something like *.pot just let me know.
  • I also followed all the other advice in the localization article to prepare the plugin for i18n and l10n.
WP Readme File:
I tried to follow every piece of advice in the links you sent for WP readmes.
  • I fixed some markdown in the "Description" section
  • Updated explanation regarding BP being a requirement
  • Added "Upgrade Notice" section about backwards compatibility / repopulating content
  • Added "Other Notes" section about backwards compatibility / repopulating content, removed filters and support / feature requests
  • Added a screenshot of the plugin on both the front and back ends
Plugin Structure:
  • Renamed cac-featured-content.php to cac-featured-main.php
  • added the BP loader code you linked to into cac-featured-content.php
  • retested to make sure everything was still working :-)

Release Plan:

What I need now is an explination of how to release a git developed plugin to the WP plugin repo's svn repo. But first I have a more basic question about git. Before I push to WP, I'd obviously like to get the 1.0.0 version pushed up to its github repo. If I didn't have you for advice, my experience would lead me to the following workflow:

1. clone current cuny-academic-commons/cac-featured-content Github repo with old code to a local working directory
2. completely delete all files from master branch
3. copy in the files from the plugin folder in my local cac repo (the files I've been working on this whole time)
4. commit these new files creating a backwards compatibility breaking master branch
5. create a 1.0.x branch just for good measure, a place to work on the support issues I'm sure will be forthcoming
6. push everything back up to the cuny-academic-commons/cac-featured-content Github repo

Does that sound like the simplest (smartest) way to go about replacing the files in the current master branch of the Github repo? If you know of a better/easier way you know I am all ears (or eyes actually since I'll be reading your response).

Once I've replaced/updated the repo I can then concentrate on an svn release workflow.

#12 Updated by Boone Gorges almost 7 years ago

Looks really great, Dom. I think we're about ready to go. A few small comments:

I left it named default.po because that's what the post you linked to called it and that was the default name in poedit. If you want me to change that to something like *.pot just let me know.

The convention is plugin-textdomain.pot. So, in our case, cac-featured-content.pot.

Does that sound like the simplest (smartest) way to go about replacing the files in the current master branch of the Github repo? I

If the plan were not to publish in the wordpress.org repo, I would say that this is perfect. SVN throws a huge wrench in things, though. Basically, you have to tend to SVN first, because SVN is too stupid to be able to added later on. In brief:
1) Create a local directory where the plugin will live
2) git-svn-clone the existing wordpress.org repo. This should work (note the -r flag, which is the first revision where cac-featured-content exists):

git svn clone -t tags -b branches -T trunk -r307867 http://plugins.svn.wordpress.org/cac-featured-content /path/to/your/local/repo/

That'll just take a second. Then, cd to the local directory and fetch all of the revisions. This will take forever (probably 30 minutes), so get a beer, or a book :)

cd /path/to/your/local/repo/
git svn fetch

(3) Once the fetch is done, create a new branch that tracks trunk. This will be used for release only. I generally call mine 'svn', but you may want something less ambiguous.

git checkout -b svn trunk

(4) Check out your master branch again, and follow your instructions from above (erase the local files, replace with your new ones, commit the changes, create a 1.0.x branch if you'd like, push it all to Github, whatevs)

(5) At release time, bump the stable tag in readme.txt and the plugin version in the plugin header to 1.0. Commit this change. Then do a straight merge into the svn branch. (Note: this is the important part. The svn branch should only be merged into, so that its history stays linear and thus comprehensible to svn. Never do any dev on the svn branch. Never rebase onto it.)

git commit -m "Bumping stable version to 1.0" 
git checkout svn
git merge master

(6) Finally, you should be able to dcommit your changes, and tag away, both in svn and git:

git svn dcommit # remember that this is from the svn branch! Never dcommit from the dev branch
git svn tag 1.0 # This might take a while
git checkout master
git tag -a 1.0 -m "Tagging 1.0" 
git push --tags

Let me know if this makes sense. There are probably other ways to do it, but this is the workflow that I've come to after a couple years messing with this crap ;)

#13 Updated by Dominic Giglio almost 7 years ago

I will change the default language filename to cac-featued-content.pot.

I was confused as I started writing this update, but I managed to answer my own questions. I'm gonna work on the final tweaks and git/svn setup today. I'll update when I'm done or if I have problems.

#14 Updated by Dominic Giglio almost 7 years ago

I've done all the Github updates described above.

https://github.com/cuny-academic-commons/cac-featured-content

I'm going to write up the release announcement post and then I can release the plugin. Hopefully by the end of today! :-)

#15 Updated by Boone Gorges almost 7 years ago

Awesome, can't wait!

One last thing you should do, when you're ready, is to write up a blog post announcement that we can trumpet from the dev blog!

#16 Updated by Dominic Giglio almost 7 years ago

Kinda what I meant by this:

I'm going to write up the release announcement post and then I can release the plugin.

:-)

#17 Updated by Dominic Giglio almost 7 years ago

The release announcement is done:

http://dev.commons.gc.cuny.edu/?p=615&preview=true

Please review and let me know if I need to update/change anything. If all looks good, I will git svn dcommit and tag the plugin for release today.

#18 Updated by Boone Gorges almost 7 years ago

Fantastic post, Dom! Pull the trigger whenever you're ready! (And let me know if you hit any snags in the wp.org git-svn deployment, as it can sometimes be a beast.)

#19 Updated by Dominic Giglio almost 7 years ago

  • Target version changed from Not tracked to 1.4.5

Moving this to 1.4.5 because I am trying to do the release right now. :-)

#20 Updated by Dominic Giglio almost 7 years ago

OMG - my first plugin in the repo!!!!!!!!!!!!!!!!

http://wordpress.org/extend/plugins/cac-featured-content/

I am testing out installing through the plugin admin interface in my local 1.4.x branch now. As long as it works I will push those changes to Github and we can (finally) close this ticket. LOL

#21 Updated by Matt Gold almost 7 years ago

Congrats, Dom! Very cool.

#22 Updated by Dominic Giglio almost 7 years ago

  • Status changed from Assigned to Resolved
  • % Done changed from 0 to 100

Thanks Matt!

Plugin has been released and release announcement has been published:

http://dev.commons.gc.cuny.edu

I am closing this issue.

P.S. - You really know you're a geek when you feel overwhelmed by your first submission to the WP Plugin Repo. LOL

#23 Updated by Boone Gorges almost 7 years ago

Dom - Thanks, and congratulations!

Also available in: Atom PDF