I have been thinking about things that made it difficult to document LEDE 17.01, and what might be done in future releases to make it easier, both for us documenters, and the folks who read it.
Here's my initial list: please comment and/or add to the list.
Only use the terms Release and Development to talk about builds, and deprecate use of "trunk" or "snapshot" in formal documentation. This avoids the problem I had writing about pre-RC1 builds that contained "snapshot" in the filename, and leaves behind the obsolete SVN-based "trunk" designation. (First step here might be to create a link for "development" on downloads.lede-project.org that points to the snapshot directory.)
Use a default LAN IP address that's different from 192.168.1.1. This would avoid a lot of explanation to avoid address conflicts setting up the network environment. In the CeroWrt project, it was enormously convenient to have its default LAN address at 172.30.42.1 - well out of any other equipment's subnet ranges.
Consider enabling mDNS with a known default name for the router, something like lede.lan. This makes it easier to write the "Getting Started" documents because you don't have to spell out a (possibly changing) IP address. Again with CeroWrt, the mDNS name made it much easier to connect to the router.
When we have general agreement from the folks writing the documentation, we can send these as requests to lede-dev list, or file them in the Flyspray bug tracker. Thanks!
Wouldn't that be inconsequent and lead to confusion again?
You are talking about "Development", but then the user is directed to a "snapshot" directory.
Release + Development
Downloads: Rename "snapshots" to "development"
Release + snapshot
Downloads: Stays as is right now
Maybe I didn't understand the problem correctly...
P.S.: Something additional to consider when changing "snapshots": The ToH + ToP use the term "snapshot" in the supported release column. To be consistent, those usages would then need to be updated too. I'd prefer to have something short there.
re: adopting "Release" and "Development" terms in formal documentation...
I see the inconsistency, and you're correct. The right thing to do would be simply to rename the "snapshots" directory to "development". Then create a symlink for snapshots -> development.
Yes, we'd have to change "snapshot" to "development" on all the Techdata pages.
I understand that concern, but first I am trying out these ideas to see if a) the documentation team even thinks they're a good idea, then b) ask the developer team to see how disruptive they would be.
Any thoughts on changing the default LAN IP address? Thanks.
snapshot is also a common term when referring to builds from projects using git.
It reflects that the images listed are a snapshot in time of an ongoing process.
I think it's going to cause more grief than benefit to change the term.
It's not just in LEDE documentation, but also in OpenWRT documentation and years
of history. Remember that the current plan is to merge and go forward with the
OpenWRT name.
well, 192.168.1 was picked to avoid 192.168.0 that most routers used to start
with. As more routers become based on OpenWRT/LEDE, whatever the project picks
as the default will become the default on those as well and the conflicts will
just come up again.
I think the right answer is that on firstboot it waits to bring up the LAN side
to give it a chance to get an IP on the WAN side, and then shift to a different
range if there is a conflict.
We already have the issue that dnsmasq won't come up if it has conflicts between
two mac addresses being assigned the same IP, having it not come up if the
address range that it's configured to issue conflicts with the range recevied by
the dhcp client would not be much worse (and if it could switch automatically,
it would be far better)
New thought to ask of the developers: Change the name of the sha256sums file to sha265sums.txt.
In its currrent state, It's discouraging to use since you can't read it at the time you want it.
To do it right, we have to add at least two (awkward) steps to the documentation. If you could click to download the image, then view sha265sums.txt in the browser, it would increase the likelihood that people would check.
Your computer's download directory gets littered with old downloaded versions.
(An aside) Perhaps we should add a note to the top of each sha265sums.txt file that indicates that a mismatched checksum should be a HAIR ON FIRE event. (Has anyone ever reported a problem?)
(An aside) It is possible to change the web server to serve up those files as text/plain, but if someone intentionally downloads the file, it's still a hassle to handle on the local machine without a sensible suffix.
I would also advocate for renaming sha256sums.gpg file to sha265sums.gpg.txt for the same reason.
This is very clever. Do you scrape all the sha265sums files?
It still doesn't feel quite as convenient as simply adding a '.txt' suffix. With that in place, you could click the download link, and while the image is downloading, scroll to the bottom and click the sha265sums.txt file. The browser displays the checksums in tab while you used another tab to get to the upload page and verify its checksum...
I reconfigured the web server to deliver sha256sums and *.gpg files as text/plain, this way they should at least appear in the browser window instead of triggering a download.
Our firmware directory listing is actually generated by a script, I could extend it to show the sha256sum next to each image download link; would that help?
That would be spectacular. It makes it seem that the sha256sum is something important, instead of making it a sideshow, hidden at the very end of a long web page.
The instructions get easier, too. They say something like, "Go to the download page, find your image. Download it, but leave that window open - you'll need it later. Open another window and [flash the image...]"
Good idea! This would make my experimental page for finding sha256sums unnecessary. First hand information is better than scraping it together and mangling it through a script.
@jow - I poked around a bit, but couldn't find the script that generates the download page. Would you send me a link? I might play with it to try to produce the page I prototyped... Thanks.
I think that it is directly the buildbot control script. "phase1" buildbot does the targets & images & target-dependent packages, while "phase2" does the normal packages.
