Handling Version Dependent Guides

I guess it's time to discuss handling of version dependent guides...

With the upcoming 'config-network-device' broad changes... we will be faced with many pages that contain config which is 19<~ || master@r167xx specific or below...

This requirement is not new but obviously this example is pretty large in scope...

I've always been a fan of moving "old-ish" config samples to the base of a page and adding some notes that it is likely only relevant for 'x' versions or may be out of date...


  • Broad search for an older config string ( ifname ) when 21.02 becomes stable and a few volunteers to add "info-box" and update the master list that the page has been handled
  • have a bot do the above?
  • something else? ( protocol for adding guides 'this guide is relevant to 'x' version when created in first place )?

Maybe not the most popular opinion, but considering that 19.07.x will fall out of (security-) support rather soon after 21.02.0, I'd personally be more of a proponent for a hard cut - document the current state, the past is done and dusted (yes, there will be a few months of overlap needed either way, but just in general (there's still the page history)).


It would be good if we could "tag" page history versions too.
i.e. this revision was relevant at 19.07.
Very difficult to maintain automatically though.


@slh I think you underestimate the time it will take for people to upgrade. Some will undoubtedly upgrade to the current version within a few months.
But there will be many people that will not -- either because they are unable to do so that fast or are unaware that there is a newer version. (This latter group is probably less technical than many and so doesn't keep updated with everything.) There will be people that cannot because something in their setup is incompatible with the latest version(s). There will be some people that cannot because they have other priorities in their life.

Given that companies that have people paid to do upgrades are notoriously bad at updating their systems, I think you're being overly optimistic that the individual, home users doing this in their spare time will be any better.

It is pretty standard practice to have documentation available for different major versions and let people choose the version they need. It's quite likely that documentation for versions > 2 major versions old could be frozen, or even any version other than the current version. But the documentation should remain available.
A standard version-control system can help manage this. Ex: use different major branches in git, each tagged for releases.

I've been working in hardware and software since the 1980s and don't think that the trends have abruptly changed.
I appreciate your optimism, though!

1 Like

Just keep in mind that in almost all use cases of OpenWrt, the device and its running firmware are exposed to the perils of the open internet and/ or the wireless range (which, in urban environments is easily in range of 20-60 households of strangers). Keeping your firmware updated is essential to keep your home network secure (to the extent possible), even if commercial vendors (and their unsuspecting users) don't do a good job about updates, there's little reason why OpenWrt should follow suit (keep in mind, OpenWrt users intentionally walked the extra mile to get it installed on their device in the first place).

While I realize that older, sub-spec, devices falling out of support is a problem for users, that shouldn't become an excuse to remain on an unsupported old version - security shouldn't be up for negotiations (beyond a couple of weeks/ months). Especially considering that most of the affected devices are about a decade old and came from the bottom of the range to begin with (802.11n, usually 2.4 GHz only, not keeping up with VDSL2 and up, etc.) - sure, they may still be good enough, but security is part of the tally.

With the wiki having a revision history for each page, removing information doesn't imply that it's totally gone - you can view the documentation from around the time when your firmware version was still golden). Yes, this is slightly more effort on the side of the user, to walk back memory lane for finding information about long-unsupported devices, but it keeps the contemporary lean and tidy, making it easier to understand without too many if-then-else constructs based on version numbers. As mentioned before, there will always be some overlap by the nature of things, but I wouldn't declare it an art form (just drop the obsolete stuff to the revision history roundabout half-way through).

1 Like

re: wiki

interim info-box has been placed on several (enough) pages to alert users to config changes and provide them with some references for self-translation...

should / can obviously be updated or changed as more references come online...