"Upgrade" vs. "Update" language

Maybe calling it upgrade/update is wrong, but it is very important to have a distinction between upgrading from one major core version to another and updating to a minor core version or updating contributed modules.

The reason: The process works different and we need to be able to explain that. For example, you need to disable contributed modules when upgrading, but it is not necessary when updating (Some do it then too which is exactly because of that naming problem and that generates a huge amount of work for them compared to just replace the code and run update.php).

I know there was was some talking regarding not using update.php for major core upgrades anymore and instead provide a way to migrate data over from an existing site with an older version. I think that would also help here, because then these two files names would actually be correct (according to the current definition of upgrade/update) as update.php would only be used to update within the same core version.

See http://en.wikipedia.org/wiki/Update vs. http://en.wikipedia.org/wiki/Upgrade

"Update" seems to be more used for repairing a product as "Upgrade" seems to be used for replacing a product with a new version.

Our problem is that we replace software with a new version to repair or improve it. So it is both.

Still, the term "upgrading" seems more suitbale for going changing between major version (D5 to D6) and updating between minor version (D5.21 to D5.22)

Problem solved! Case closed ;)

I think we all agree on Upgrade.

Upgrade from the link you provide:

When there is a new major release, you might want to upgrade to this to get new and powerful features.

And that's what's in the 'Upgrade' Documentation.

Upgrade = Full new version 1.19 -> 2.0 or 6.21 -> 7.0

Update is a bit more ambiguous, but it all depends on the context of the term. I had to use 'update' to in the docs to differentiate bringing your current site up to the most recent versions prior to actually upgrading. I think that makes sense in that context.

When talking about re-writing modules - well that's a different context. I would call it updating source code or rewriting source code. The point being that it is the source code that is being 'updated' and not the installation of the module.

p.s. I honestly do see where anyone could be confused. Particularly when we explicitly define the terms.

There still seems to be a difference of opinion. Should Drupal use "update" for minor upgrades within a major version, and "upgrade" for a change of versions? While @arianek's proposal for update = push, upgrade = pull sounds inviting at first, I think it would be more confusing for people trying to maintain their Drupal sites ("We offer an update so you can upgrade."). At any rate, the first order of business is to agree to use the terms consistently, both in the documentation and in associated file names. Then we can consider whether "update" should mean one thing and "upgrade" another. I think that many users would still find it confusing to be sometimes confronted with an "update" and other times with an "upgrade". Perhaps the best would be to call them minor and major upgrades? Or, minor and major updates. The instructions could be quite different for the two paths. Just don't mix update and upgrade willy-nilly. They should mean two very distinct things, assuming that both terms continue to be used.

With commercial software I've always seen "upgrade" used when talking about major versions with new features (usually costing money), and "update" for minor versions that mainly fix bugs (free).

Please note that the upgrade/update terminology as defined in the 'Drupal 7 Upgrade Guide' handbook page is even now not consistently used. Take this recent security release created by the Drupal Security Team as an example (emphasis mine):

• If you are running Drupal 6.x then upgrade to Drupal 6.18 or Drupal 6.19.
• If you are running Drupal 5.x then upgrade to Drupal 5.23.
• Drupal 5 will no longer be maintained when Drupal 7 is released. Upgrading to Drupal 6 is recommended.
• The security team starts a new practice of releasing both a pure security update without other bugfixes and a security update combined with other bug fixes and improvements.

So it seems that 'update' refers to a new version of Drupal or of a contributed module while 'upgrade' refers to the act of applying those updates.

In this case:

• Update = a noun. Example: There's a new security update for Drupal 6.x and for the token module.
• Upgrade = a verb. Example: Make sure to upgrade your Drupal installation to these newest versions.

I don't have a preference between what has already been suggested (update = minor version, upgrade = major version) or what is used here, but I think we should pick one model, document it as a standard in the acronyms and synonyms and terminology pages, and apply it consistently on d.o and x.d.o.

Agreed that the common usage in Drupal is upgrade to a new major version, update to a new minor version— whether it's coders changing the software or users updating (Drupal 6.18 to 6.19, Views 2.10 to 2.11) or upgrading (Drupal 6 to 7, Views 2 to 3) their site.

The best word for what a module developer does to take a module or theme to a new major version of Drupal is port, and then the same update/upgrade idea for minor/major versions of that project (2.1->2.2 vs 2.x->3.x).

Okay so there is a bit of confusion on my part.

I thought we were talking about the 'new' upgrade guide.

http://drupal.org/node/548922

I think the language is more consistent there.

but it's inconsistent with everything else in the older documentation

And by "everything else" do you literally mean all documentation anywhere on Drupal.org or just Upgrade and Update documentation.

My understanding is that the new Upgrade Guide is meant to replace the old one. (Provided someone writes the CCK to Fields migration process documentation - which is the only major piece missing from the Upgrade guide).

If the new guide is using the terms consistently, I don't know how much we have to worry about the old one since it will just get archived away never to be viewed again.

These words are sufficiently interchangeable as to be synonymous. I propose that we do not make any distinction between the two, as the context in which they are used generally makes the meaning clear.

If you are talking about moving your site from D6 to D7, it's clear that's what you are doing.

If you are branching your module from a 1.x to a 2.x branch, it's clear that's what you are doing.

If you are writing code to make your 6.x module work in D7, it's clear that's what you are doing.

If you are changing your core version from 6.18 to 6.19, it's clear that's what you are doing.

I'd rather see us focus on explaining these processes more clearly - given that the two terms are so close in meaning, I don't see what is to be gained from enforcing an arbitrary distinction.

And then, let's see how that works for the sizable percentage of the community who is not a native English speaker.

As a case in point, consider the following excerpt from the handbook:

In the Upgrading from previous versions section, we have the Version update considerations page.

In the opening line, it reads: "There are several approaches to upgrading your site. Unless you do this often however, you may miss a few other considerations when updating from one release to the next." (emphasis mine)

So, to get started here, in the "Upgrade" section, we have an "Updating" page that mentions "updating" and "upgrading" in the first sentence.

Then, in the descriptive points, we describe the process of "upgrading", but to do this we go to "update.php" -

However, from the context it's clear what we are trying to explain: change the codebase of a drupal site from older versions to newer versions.

Enforcing strict definitions here would actually make this page less clear.

That section with upgrade=update, Upgrading from previous versions, is the old documentation with the usability problem that there is not enough differentiation for the frequent minor updates (security and bug fixes). These are unnecessarily complicated for users with the same long major D6->D7 procedure for new API (disabling all contrib, etc.).

I think that's the reason why the new D7 docs -and it seems the new UPGRADE.txt, both in the works- use more specific terminology: they are different procedures.

Anyhow, I think only the upgrade/update step-by-step instructions are important, not so much the terminology. In my case, when writing posts, etc., I'm using the new "major upgrade" and "minor updates" naming. However, while there are different opinions about this, it could be -rather than an enforcement in the documentation- maybe just a flexible recommendation for greater clarity, only taking the time to correct doc contributions when there is confusion in some text. Well, just a possible middle point: Preferably use the word "upgrade" between major versions and "update" between minor ones. While there is clarity, the naming is not so important.

Update is in my opinion an actualization and upgrade an actualization with the change of the version number.

Coming from commercial software it's pretty clear as also been said here, "Upgrade" is typically from one Major version to next or a higher and something you pay for, while update is sort of bugfix/maintenance and usually free.

I was originally in favor of something simmilar here but after reading #15 I actually changed my mind and think it's spot on. What's really is important is to decide for a defination and then stick to it, as well as be clear of what contect it's about in case the location doesn't make it obvious.

In the end there always will be some getting confused about upgrade vs. update just as some having problems to be sure about what is left and what is right.

Re: #15

These words are sufficiently interchangeable as to be synonymous. I propose that we do not make any distinction between the two, as the context in which they are used generally makes the meaning clear.
…
I'd rather see us focus on explaining these processes more clearly - given that the two terms are so close in meaning, I don't see what is to be gained from enforcing an arbitrary distinction.

I must strongly disagree. It is only confusing for users, because they see "update" and "upgrade" close together, and wonder if these are two different things (and they missed an explanation somewhere). They may well be intended to be synonymous or interchangeable, but they don't come across that way. We can use both — with distinct and rigidly enforced meanings, explained to users in a glossary or footnote, or we can stick to one for all uses and ban the other. It only sows confusion to use these two words interchangeably. Once you've had it explained to you that they basically mean the same thing (and you remember that), there's no problem, but for the majority of users, they're going to be very confused and concerned for a while. Even if they can eventually figure it out, it's a waste of their time and effort to be put through that.

There's what we'd like, and then there's reality.

What we would like is to have "rigidly enforced definitions" that are used correctly, every single time any person sits down to write documentation.

Reality is that we have two words that are nearly identical in meaning, used interchangeably throughout documentation and even in core (update.php, and most likely in some core documentation, although I admittedly I haven't audited the docs for that).

It will not "sow confusion" to use the words interchangeably *unless* we give them specific, rigidly enforced definitions. If we attempt to enforce definitions, the very act of enshrining the definitions will make many sections of our documentation - and core - "wrong" - and (in many cases, anyways) not because there are any real problems with how the existing docs are written, but because these words have been used interchangeably for years.

The context in which these words are used will define their meaning. We should focus our energy on cleaning up/clarifying existing documentation, which would be a much more effective way to minimize confusion. Do you fix something, or improve something? Do you sleep, or nap? Do you change, or revise? Do you upgrade, or update? The "right" answer is determined by context.

@juan_g in #17, re

I'm using the new "major upgrade" and "minor updates" naming

I like this, partly because the use of the adjective provides some needed context around the scope of the interchangeable nouns. In a doc where both processes are described at once, having some consistency with the naming would definitely be helpful, and this is a situation where the context (talking about both processes at the same time) requires a higher level of clarity. I also like your suggestion of having this be a suggested convention, as opposed to a rule.

I use them somewhat interchangeably, with upgrade usually reserved for major releases, and update for more or less anything else. While I think it's a good idea to try to figure out some kind of usage guidelines, for me it's more important to figure out all the contexts - the main problem with UPGRADE.txt at the moment, is that it doesn't distinguish between two completely different processes.

Let's consider bonobo's list and add some more:

Upgrading your site from D6-D7
Updating your installed core version for a minor release (6.18-6.19, 7.0-7.2).
Updating a contrib module for a minor release (6.x-2.1 -> 6.x-2.2)
Updating a contrib module for a major release (6.x-2.1 -> 6.x-3.2, and also 6.x-2.1 -> 7.x-3.2, although the latter is part of the major site upgrade process).
A hook_update_N() (an update) - these run both for minor and major releases, for both core and contrib, and always via update.php
Module maintainers updating their modules for major Drupal core releases.
Module maintainers updating their modules for major Drupal contrib releases (Views 3, Token 2 or whatever).

For me, based on that list, which may not be complete, I think I'd reserve 'upgrade' for the process of moving between major core releases. As part of that overall process, you also do a lot of updating - replacing contrib modules with new versions, updating custom themes or modules, updating site configuration, but it's a much wider process, and one that isn't in the normal cycle of site building and maintenance.

When you upgrade for a minor core release or minor contrib release, you don't usually have to make any changes to your actual site - theme, business logic, infrastructure, whatever. There are very, very few sites which would be able to say the same for a major core version upgrade

Hopefully this won't muddy things, but I'm also going to guess that the vast majority of Drupal sites have never been through a major version upgrade. According to http://drupal.org/project/usage/drupal is looks like of the Drupal 5 sites that report usage information, the current number is 13,000+, and the highest ever peak was 24,000. This is only a small subset of Drupal 5 sites, but it likely includes some of the better maintained ones. If we assume that not enough newly built sites get added to the Drupal 5 stats to make it statistically significant, then that's more than 50% who haven't done the upgrade to D6 yet. One fairly large 5-6 upgrade I worked on (started around this time last year, was launched in February), was precipitated by the fact that Drupal 7 might have been released February-April this year (haha, but that seemed quite likely in August 2009..), and that Drupal 5 modules had more or less stopped development, end of life was coming soon etc. On top of that, probably of all Drupal sites ever built at this point, the majority likely started on D6 (that's a complete guess, would be happy to be proved wrong), and by definition a Drupal 6 site can't have gone through a major version upgrade.

All this means that it's very important to make that distinction, I would say that 'upgrade' is primarily a process that happens to a site, and 'update' is what happens to the code and database regardless of whether it's a major or minor release.

batigolix wrote (#3):

See http://en.wikipedia.org/wiki/Update vs. http://en.wikipedia.org/wiki/Upgrade

"Update" seems to be more used for repairing a product as "Upgrade" seems to be used for replacing a product with a new version.

Benjamin Melançon wrote (#9):

Agreed that the common usage in Drupal is upgrade to a new major version, update to a new minor version— whether it's coders changing the software or users updating (Drupal 6.18 to 6.19, Views 2.10 to 2.11) or upgrading (Drupal 6 to 7, Views 2 to 3) their site.

The best word for what a module developer does to take a module or theme to a new major version of Drupal is port, and then the same update/upgrade idea for minor/major versions of that project (2.1->2.2 vs 2.x->3.x).

Even if not always followed, this major upgrades and minor updates terminology seems a quite common, simple and clear usage, for both site builders and code developers (who usually also are site builders themselves).

It may be worth suggesting that module maintainers tell site builders that they need to do a major upgrade from 2.x to 3.x, because this is generally a very different act from a minor update – like with a Drupal version major upgrade, things may not look or work the same, while with a minor update they are generally supposed to, although this will be a lot less consistent in the world of contrib. And telling module developers to port their modules between major versions of Drupal also makes sense; it's precise and it prevents some word overload; but it's not really related to the usages being described here.

In the main catch is very persuasive, and a version of #23 would make fine guidelines.

+1 to what catch lays out in #23.

catch wrote (#23):

I think I'd reserve 'upgrade' for the process of moving between major core releases. As part of that overall process, you also do a lot of updating - replacing contrib modules with new versions, updating custom themes or modules (...)

All this means that it's very important to make that distinction, I would say that 'upgrade' is primarily a process that happens to a site, and 'update' is what happens to the code and database regardless of whether it's a major or minor release.

I find this mixed terminology confusing for users: at the same time, you are upgrading core and updating contrib; as a site builder, you are upgrading, and as a code developer you are updating; etc...

IMHO, we should keep it simple, with the same naming guidelines for core and contrib, for builders and coders.

In summary, major version is a complex API change, minor version is different, a much simpler process. It's better to distinguish them more clearly. I think that's the point of this issue.

@juan_g

In summary, major version is a complex API change, minor version is different, a much simpler process.

What about (what we now call) security updates? While they are "simple" they are very important. Do we keep the 'update' term?

I think "security update" seems right as it is, yes. Even when they are important, the process is usually similar to a bug fix; an API change isn't needed in most cases.

So an "update" is a relatively minor operation, with relatively little to do (say, drop in a replacement file), while an "upgrade" is a much more involved process, requiring shutdown of this and disabling of that and removal of something else and updates/upgrades of other things (co- and pre-requisites)? As long as there are clear guidelines for when to use each term, I can live with that. Just don't use them interchangeably! If needed, go back and fix earlier documentation to say the right thing.

While we're on the subject, is it really necessary to completely overwrite all files when updating from 6.17 to 6.19? Would just providing replacements for changed files (packs for each level, applied in sequence) be better, or is there some sound reason for overwriting everything? If not, why is an update packaged as a complete install? Rather than hijack this thread, feel free to start a new discussion thread, or provide links to ongoing discussions on this subject (I'm pretty sure there are some already). See also other products such as SMF (simplemachines.org), which distinguish between install packages, small upgrades (1.1.10 to 1.1.11) with just changed files, and large upgrades (use if jumping multiple levels) with all files. They also have a package manager for installing packaged changes (small upgrades, mods, themes, etc.).

@Druid: if you manage your core installation via version control, that makes the process of minor updates much, much simpler - cvs up -dPR, check that back into whichever vcs you use to keep your site's code in, run update.php, more or less done.

Makes sense to use 'port' for dealing with API changes per Ben.

catch wrote:

Makes sense to use 'port' for dealing with API changes per Ben.

Benjamin Melançon's #9 is interesting because, while he says a common usage is "upgrade to a new major version, update to a new minor version— whether it's coders (...) or users", he also takes into account that modules and themes can have their own major versions independently of core versions. It's true that "port" (or "convert" to work with a new major core version) is also commonly used for modules and themes.

For example, according to his explanation:

Update core, modules or themes to a new minor version

• Drupal 6.18 to 6.19
• Views 6.x-2.10 to 6.x-2.11

Upgrade core, modules or themes to a new major version

• Drupal 6.19 to 7.0
• Views 6.x-2.11 to 6.x-3.0

Port modules or themes to work with a new major core version

• Views 6.x-3.0 to 7.x-3.0

@Druid Without going off-topic too much, Chris Shattuck has a guide on updating Drupal (minor versions) using patches.

@arianek #35 I'm still ready for the review ;)

My advice would be to start with a summary, and then clarify the difference some more. I applied this here, changed some styles for readability and included links to more documentation:

An "upgrade" is an involved process that impacts the whole site, while an "update" is what happens to the code and database regardless of whether it's a major or minor release (for instance by dropping in a replacement file and running update.php). When describing processes for end-users or developers to "update" or "upgrade" core, modules, and themes, be as consistent as possible using these terms. Learn more about major and minor releases.

Upgrade

"Upgrade" should be used only for the act of performing a major version upgrade, the process of moving between major core releases. For example:

• When upgrading your site from Drupal 6.x to Drupal 7.x, be sure to fully back up your site before beginning.
• When you upgrade Drupal core from 6.x to 7.x, you must also upgrade each module you have installed, as well as any themes that are not part of core.

Update

"Update" on the other hand, should be used for minor version updates or the task of modifying a module/theme you maintain to a subsequent release. As part of the overall upgrade process, you also do a lot of updating; replacing contributed modules with new versions, updating custom themes or modules, updating site configuration. For example:

• You or your development team should update your installed core version to the next minor release (6.18 to 6.19, or 7.0 to 7.2).
• You or your development team should update a contributed module to the next minor release (6.x-2.1 to 6.x-2.2)
• You should update a contributed module for a major release (6.x-2.1 to 6.x-3.2, and also 6.x-2.1 to 7.x-3.2, although the latter is part of the major site upgrade process).
• A hook_update_N() (an update hook) may be run both for minor and major releases, for both core and contributed modules/themes, and always via update.php
• Module maintainers will be updating their modules for major Drupal core releases.
• Module maintainers will be updating their modules for major Drupal contributed module releases (eg. Views 3, Token 2).
• It is important to inform your client that their site needs security updates.

Port

Alternately, for developers, the term "to port" can be used for the act of updating their modules between major versions of Drupal, for example "I have yet to port my module to Drupal 7".

#40 Excellent!

+1

Looks very good, but according to what you've written, shouldn't it be "When you upgrade Drupal core from 6.x to 7.x, you must also update each module you have installed, as well as any themes that are not part of core."?

@zirvap Ah you are correct. The same example written from the update perspective:

"You should update a contributed module for a major release (6.x-2.1 to 6.x-3.2, and also 6.x-2.1 to 7.x-3.2, although the latter is part of the major site upgrade process)."

@arianek Do you agree to change that example?

Yes :)