Dear Developers, if you follow these simple guidelines, your Drupal Features will be much more useful to institutions like Stanford over time. You will win friends and influence people. Drupal will live up to its potential, and there will be much rejoicing.
1. Small Features, Loosely Joined
For institutions like Stanford that have multiple Drupal projects all happening at the same time, spread across different teams, it is important to establish norms that make reuse more likely. For Features, smaller is better. The atomic unit for a Feature is the Content Type. If you do nothing else, make one Feature per Content Type and resist the temptation to put anything else in it. Whatever else you got going on: Views, Rules, Feeds, Services, etc. keep all that stuff in separate Feature(s) that list the basic Content Type Feature as a dependency. To maximize its reuse potenial, your Content Type Feature should not itself have any dependencies on other Features*. It’s common for developers to use a <prefix>_base Feature that bundles common site attributes (like image styles and variables) that all the other Features depend on. In our case it’s better to either a) not do that, or b) make it easy to discover and undo that.
2. This is my prefix. There are many like it, but this one is mine.
One attribute that all highly reusable Features have in common is a prefix, consistenly applied. I have stood up a hasty prefix registry on techcommons (until we decide to make a better one). Each unit of the university should use just one prefix over time. This will take a little care and attention, but I have faith in us. Here are some of the existing claimed prefixes. If you have a small project inside one of these organizations, please use these instead of registering a new one:
- gsb_ (Graduate School of Business)
- soe_ (School of Engineering)
- earth_ (School of Earth Sciences)
- dor_ (Dean of Research)
- stanford_ (Stanford Web Services)
To see the complete list, and to add to it, please visit techcommons.
3. Namespace them thar fields!
Many of you are already making Kit-compliant Features. That’s good! (We like Kit.) So please do read and follow the Kit spec for Features. We also need to extend Kit some. Our primary concern is field name collision, or anything else that would prevent a Feature from being successfully introduced to a new Drupal site outside its original distro. Like most everything else in Drupal, we do this with prefixes (technically, for fields these are infixes).
Things we prefix:
- Modules and functions (natch)
- Content Type machine names
- Views machine names
- All the things
The Cantor Center is creating a Drupal Feature for their exhibitions. They know that prefixing is important, and they don’t want to collide with similar projects currently underway by the Department of Art and Art History or the Libraries, so they employ the prefix cantor_ consistently across all their properties, and edit the techcommons page to let others know that they have done this.
Content type: cantor_exhibition
You’ll notice that we use a version of Hungarian notation, whereby the machine name indicates what that thing is. For field names this can be a little challenging due to the 32 char limit on field names (and Drupal uses up the first 6 with field_ ) but if we all stick to this convention our Features will get along with each other, and as a University and an open source community we stand to gain a great deal more over time as increasing number of these Features become Highly Reusable Features. (HRF? I’m trademarking it! I want a quarter any time someone says it!)
If we do nothing other than harvest the humble Content Types from our various projects, that alone is a huge win for us. This point may get lost in some of the flashier Drupal applications being built these days, so it’s important to call out: Drupal is a marvelous content modeling framework, and the Content Type contains a lot of important information about a particular domain or group that is highly shareable. We don’t have a single, uniform higher-ed use case. We have hundreds of use cases. The Content Type emerges as an extremely relevant and legible artifact of prior work that we can learn from, adapt, and develop over time. We are looking for development teams that are willing to join us in this endeavor (and show the perseverance to slog through overly verbose blog posts!).
Call me maybe
Any development team that wants to connect directly with me to discuss our Features best practices is more than welcome to do so! The absolute best time to do this is when the content model is just taking shape, before you make your first Content Type. There is one vendor team that already is doing all of the above consistently (you know who you are; thank you!) it would be amazing if we get to a point where everyone does.