Features Part 2 - Managing your feature
In the previous post we built a basic blog feature. This post will cover details on how to manage that feature (i.e. update, revert, etc.).
Prerequisites:
You don't need much to get going with this, but what you will need is:
- Read through the previous post and can build a feature
- Basic use of Drush and the command line
I'll cover drush in more detail in a later set of posts, but for now it's important that you install Drush if you haven't already. Features includes a set of Drush commands that are used to update and maintain each feature. These links should help get you started with Drush:
- Drush project page
- drush.ws site
- Drush readme with installation instructions.
Note that if you're doing this on a D6 site, the Drush 7.x version will work. Drush is not a module in the traditional sense, and it's Drupal version agnostic.
Terminology
If you browse back to the features admin page (admin/structure/features) the example blog feature should be enabled (enable it if it's not). Features will take notice of any changes you make to any of it's components and tell you they've been "overridden". Due to some of the things that one can do with features, the terminology can occasionally get a bit ambiguous, so it's probably important to define a couple of the terms used:
- Default (state): All settings in your feature identically match their respective settings on the site (this is the state you're after :) ).
- Overridden (state): The components of the feature used in the site no longer match the state of them in the feature module. For example, if you were to use the Views UI to change the number of blog posts listed on a page from 10 to 15, your feature would now be overridden as your site is displaying 15 posts, but your feature module specifies 10 posts.
- Needs review (state): This is effectively the same state as overridden, but generally means there are more complicated changes and it's recommended you review the differences prior to reverting the feature.
- Revert (action): You can revert an overridden feature to make the site settings match those in your feature module. In the above example you set your site to show 15 posts instead of 10 posts in a blog listing. If you decide that you no longer want that simply revert the feature and you'll be back to 10 posts. Revert is probably the most confusing term used with features.
- Update (action): Updating a feature is the exact opposite of reverting one, instead of reverting your site to match your feature, you'll update your feature to match your site. In other words, if you prefer to have 15 posts lists, update your feature to bring it back in sync. This will change the setting from 10 to 15 posts in your feature and take your feature back to a default state.
Diffing a feature
So let's give the above a try. Change the display settings on your blog listing view to show 15 posts instead of 10 this will mean our blog feature will no longer be in sync with the settings on the live site. Back on the features listing page you should see that your blog feature is now "overridden".

Click the overridden link to bring you to your full feature page.

The above image shows that the overridden component is "views". If you've enabled the Diff module, the word overridden will link to a diff between your site and your feature (the "review overrides" tab will also give you the same thing).

Reverting a feature
After reviewing the changes, if we've decided we don't like the changes (perhaps another site admin made them, after all), we can revert the feature. Simply select the components you wish to revert (in this case only views) and click the "Revert components" button.
Your site will now be reset to match the code in your feature module and display 10 posts again instead of 15. I've occasionally experienced caching issues where the component is still listed as overridden instead of default as it should be. Flushing caches should sort this out.
Updating a feature
Ok, you've changed your mind now and do actually want 15 posts displayed on your blog listing. Head back to views and switch the number of posts to display to 15.
We now want to sync up the features code so that it matches the site. This way when we take the feature to new sites it will also show 15 posts.
On the command line change to your site folder for this site (sites/blog.scotthadfield.ca perhaps). Run the command:
$ drush features-update example_blog
example_blog should be replaced with whatever you named your feature.
Features and Drush
Though updating your feature is the only thing Drush is required for, you can perform any feature management actions directly in the command line. drush help
shows the following commands:
All commands in features: (features) features-diff (fd) Show the difference between the default and overridden state of a feature. features-export (fe) Export a feature from your site into a module. features-list (fl, List all the available features for your site. features) features-revert (fr) Revert a feature module on your site. features-revert-all Revert all enabled feature module on your site. (fr-all, fra) features-update (fu) Update a feature module on your site. features-update-all Update all feature modules on your site. (fu-all, fua)
We've diff'd, exported, listed, reverted, and updated our feature now, which covers all the bases for feature management.
Pitfalls
I can't stress enough the importance of keeping your site in sync with your features. If you're lazy and your features are perpetually listed as overridden you're going to be in for a world of hurt. This is particularly true when using a dev -> stage -> prod
workflow with features or working with multiple site builders at one time.
NEVER have two different developers working on the same features components at the same time. For example, if developer A updates a view in the blog feature and then updates their code from developer B who updated a different view in the feature, developer A will need to redo their work after reverting the feature. This is equivalent to two developers working on the same line of code in the same file at the same time. There will be conflicts. With that said, it is possible for Developer A to update the content type while Developer B updates a view.
In a simple workflow you'll update the feature in your local dev environment, then push the changes to stage, revert the feature on stage (this is where the ambiguity of the terminology really comes into play :)), test, push to production, revert the feature on production, test.
Make as few changes as possible to the feature on the live site, i.e., even configuration updates should be done locally first and pushed out. This way you'll be less likely to break the live site and you won't run into nasty conflicts with your features as you develop the site.
What if you want to use the same feature on two sites, one which will display 10 posts in the listing and the other 15? This is where "fully" re-usable features come into play. Instead of forking your feature it is possible to give them settings of their own. I'll be going into more detail on this in my the third post on features.
- Login to post comments
Peanut Gallery
Could you speak a little about...
Thanks for taking the time to write down your thoughts. I'm curious about some of your experiences with...
1) Building kit-compliant features. Pitfalls? Why or why not do you create kit-compliant features?
2) How do you keep permissions from being overridden when each site could have different roles? anonymous and authenticated are in drupal core and administrator is a de facto standard. But what happens when you have editor, or other site-specific roles that require permissions being set?
3) Have you been able to include features from external sources? I understand that this is just an example for study, but there's got to be a "simple blog" feature already built out in the wild and available on a feature server. I would imagine that these external features would be overridden most of the time as you configure it to fit in with your site.
4) How do you handle views blocks in a feature? I'm not aware of any approach that would allow boxes to be used as a views display. Or is that getting too far into the ambiguous "is it a feature, module, or app" conversation?
5) How often do you run into a situation where something just isn't exportable? Short of implementing features for the module yourself, how do you handle those situations?
6) How often do you find yourself pulling your hair out because a feature just won't revert? ;) http://drupal.org/node/744450
My use and approach to features is still evolving. But the main benefit I've seen in my workflow is that features becomes a time-saver because they can provide a starting point for a new site build (input filters, wysiwyg profiles, event content type, etc). After the initial install, I configure all the settings to match up with the site. That usually means most of the features are overridden immediately after the initial install. But I'm looking forward to your next blog post to see if your approach to creating "fully" re-usable features will help.
The next post will have more details
Great questions! :)
1. In all honesty, I don't have a lot of experience using Kit, but I will be doing it as part of this series. The next post will touch briefly on this, but mostly I'm sending people here for now:
http://affinitybridge.com/blog/build-kit-abridged-or-every-site-drupal-distribution
2. In that case I will have a site specific feature that I roll all my permissions into. I've found that in general permissions only make sense on a case-by-case basis. In the example in the previous post I've brought in the permissions too, but you're right that probably won't work too well unless the site is very similar.
3. I've never used features from external sources. I believe due to the lack of prevalence of kit style sites, this is still a hard problem to solve. I would be quite curious to know if anyone offers feature servers to download prebuilt features from. I know some companies are working on "app stores" now that will basically take this concept to the next level, but don't know how far they've gotten.
4. I'm not sure I understand this question. The feature here has views blocks already. And what do boxes have to do with views blocks? You'd really only use boxes if you wanted a custom block on the site.
5. All the bloody time. For simple cases I can write a patch myself, but I generally don't have time for the more complicated scenarios. If you really need it to be handled in a feature though, you'll have no choice but to write some ctools export integration yourself. This is something I should /definitely/ write more about.
6. This happens occasionally too. Primarily when I've removed items from the feature. Also it sometimes happens when I've forgotten to enable a module on the staging site and the feature won't revert for obvious reasons. Normally I just completely trash the feature module folder and then rebuild it fresh. I didn't realize there was such a ticket for it, next time it happens to me I'll try and debug it to help sort out that one.
I hope you'll find the next post useful where I go into making features completely re-usable and you won't have to worry about changed settings overriding the feature. I'll probably put it up on monday.
Great questions and answers!
dkingofpa, nice set of questions, and Scott, thanks for the excellent answers!
I'm looking forward to a future post on issue #5. :)
Wow, Great post. Keep it up
Wow, Great post. Keep it up
Kit maintenance
One issue I feel on "kit compliance" is that no one is mantaining it. And it is a hard task if someone wants to step up to it. Development Seed proposed kit to make it easier for Drupal shops to develop features for OpenAtrium, undoubtedly the most popular Drupal distribution. It takes some authority to keep a Kit standard, and it is worth nothing if there are heavyweight noncompliant distros all over the place.
All in all, it means Phase 2, Lullabot or any other DIstribution mantainer should step up. But I don't see it coming any soon.
I think we need the features first
I think that's quite a fair point. Basically for the vendors there's currently limited benefit for them to be kit compliant. What does it get them in the immediate future? Not a whole lot right now. But once re-usable features start become more mainstream they will need to support a common standard, and the only option for that atm is Kit afaik.
So if all of a sudden there's two dozen features you could plug into your distro but they won't work due to your not being kit compliant, you'll finally have some incentive to change things.
Blocks fail
I added Features extra and created a feature with the block I created, added it to a panel, exported the block feature and panels feature, but it won't appear in the target server. The Block does appear, but the panel won't get updated with it. What could I be doing wrong?
Hey @JValentin... I'm not
Hey @JValentin... I'm not sure if blocks are exportable in features yet. You should try out the "boxes" module. I also have very limited experience with panels but it's possible they're not fully exportable?