On Thu, Oct 25, 2018 at 10:39 PM Petr Bokoc <pbokoc@xxxxxxxxxx> wrote: > > Hi docs, > > For the longest time we used to maintain a revision history for each > book we published on docs.fp.o. However, they weren't particularly > useful, each revision was noted by the date, author, and an unhelpful > note like "updating for Fedora 21" or "async update", without a list of > specific changes made. The revisions were basically only added because > the old toolchain used for Red Hat docs required it, and contributors > from Red Hat built a habit of adding them and did it in Fedora as well. > > The current books (Release Notes, Installation Guide, and System > Administrator's Guide) still have revision histories, but the Install > Guide and Sysadmin Guide have last entries from 2016 and 2017 and the > Release Notes have an empty one (which makes sense since we completely > rewrite the book for each release, but I don't think people add new > entries if they republish). It's more confusing than useful at this > point, and I think we should do something about it. > > The way I see it, we have two choices: > > * Start maintaining proper revision histories with much more detail. > This would require every PR or commit to also add something to the > revision history, which means another thing to keep in mind and a little > bit of extra work. There's also a potential problem about the date: when > you add a revhistory entry, you have no way of knowing when it's > actually going to be published, so you have to use the current date - > but the reader doesn't care about when you commited it, the only use for > a date in a revhistory is for the reader to see if anything changed > since they last checked. How about a hybrid here of encouraging good git commits, ideally with the merger pushing back if they are just "changed stuff." I realize that puts a lot of work on you Petr, so I deliberately say "encourage." > * Just get rid of revision histories altogether. We'd lose a potentially > useful feature but in its current state it's useless anyway. +1 > A third way would be to automatically insert a "last modified" timestamp > in every page's top bar; the timestamp would ideally contain a link to a > set of commit diffs relevant to that page with dates. That seems > difficult to implement though, so I don't think that's an option - > unless we could insert that timestamp during the CI/CD process when we > have one, I suppose. I'd like a last updated timestamp if we can get it. Can we Adam? regards, bex > > What do you all think? > > Petr > _______________________________________________ > docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx > To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx > Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html > List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines > List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx -- Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx Fedora Community Action & Impact Coordinator @bexelbie | http://www.winglemeyer.org _______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://getfedora.org/code-of-conduct.html List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx