@glyn.hudson Sounds like a great idea.
Node-red uses http://semver.org/ as a template and reference for semantic versioning. It would be good to follow a similar (if not the same) model.
Paul
What prompted it was that I saw an announcement from PlatformIO who also use Discourse.
Locked is good, if you want to comment just do a linked post.
Make them sub categories so Emoncms > Announcement
Pinned doesn’t really help as it does not provide a history. Sometimes useful to see what has changed if you are jumping versions (yes I know it is on github if you look hard enough.
Limiting access is not an issue I think just good practice. There are already multiple levels within the forum anyway.
Trouble with the github releases is that, as far as I can see, it is impossible to see releases of modules.
YMMV
{edit}
Went and had a look at that App post and it is an excellent example of why an announcement category is useful;
- Multiple issues with the module get reported ina single thread
- Later updates to the module get ‘announced’ within the same thread, sometimes well after the original change.
I agree with Brian. Comments on an announcement would just be a major distraction.
An announcement isn’t a solicitation for comments, rather it’s just as the name suggests, news.
The proper place to hash it over, talk about it, etc, is the discussion forum.
Agree here,
and here as well.
I concur.
Me too, I support Brian’s suggestion.
Paul
This is because there is no ‘stable’ branch for Modules. Currently every commit made the the master (or 9.0 branch) for some modules is ‘released’ i.e this is the branch emonPi’s pull from. As I mentioned above, we’re looking to change this.
The new app module post by Trystan was not really a release just a notification that there had been changes committed. There are lots of amazing contributions being made the the Dashboard module almost daily. Following the commit log is the only way to track these changes currently: Commits · emoncms/dashboard · GitHub
Agree, I can see your point that pinning posts does not allow users to review older announcements in the future.
I think a good compromise would be to tag all announcement posts with the “announcement” tag. Making an announcement sub-forum for every single category and sub-category would results in lots of extra sub-categories which could quickly gets messy and confusing.
As an example, I have tagged Trystan’s app module post, Android app release and EmonPi setup wizard with the ‘announcement’ tag. Feel free to tag other posts you deem fit with this tag. You can browse this tag by clicking on announcement tag or following this link:
I agree, whether you call it an announcement or a changelog, It works well for the Emoncms Android App change log (last updated by @glyn.hudson 4 days ago) and it worked very well when @nchaveiro maintained a changelog for emoncms on the old forum
…a further thought is to create a sticky, read-only ‘Announcements’ post, which would contain links to the respective changelog files in git.
Using node-red as an example;
Updates & changes
Users can then click through, find new additions and the changelog history.
Paul
The only issue with that is that you would not get any notification of a new post / announcement. A separate (sub) announcement group (?) under emoncms would be the cleanest route. Announcements - PlatformIO Community
I do agree Brian, but Trystan & Glyn don’t seem supportive of that approach, so I’m trying to reach some middle ground where T & G get versioning, and users can access the changelogs without searching through github.
I’ve just made a start on versioning in the dashboard module (v1.0.1) and introduced a changelog, which although is a bit bare at the moment, it will include any changes made from now on, and should at least allow users to see what has changed.
In the second post in this thread, Glyn has intimated that they are working towards displaying the modules versions in the emoncms admin page, so users can then compare versions, and see what has been added before updating.
The URL of the dashboard changelog is https://gitprint.com/emoncms/dashboard/blob/master/CHANGELOG.md
Paul
I’ve just updated the changelog URL to use gitprint.com to display the changelog in a easy to read pdf format.
Does this look better?
Dashboard changes & updates
Paul
1 Like
Looks good. Is this assumed to be stable branch? Might be worth stating if so (or state the branch). I always think it is worth a link from a changelog to documentation on how to do any update 
I think the need to have a “announcements” thread that users can subscribe to (and retain the option to turn off other email alerts) is important.
Back when I started the emonHub repo, I suggested an “announcements” issue be used on the emonHub GitHub repo so that we could recommend users subscribe (watch) that one issue and never miss an important update and also not get bombarded with daily activity and other unimportant stuff.
I think the best way forward is to have the “official announcements” ONLY published on a dedicated thread, this only needs to be updated when there are important releases eg a major bugfix or substantial feature, not every commit!
This would be where the user friendly & nicely formatted version should exist and a more formal changelog.md be maintained on the repo as you have done on the dashboard repo. However I think the title and the formatting is superfluous and would suggest we keep it as simple and clean as possible, easier to maintain and copy over to the forum “announcements” less frequently.
If the changelog.md had less formatting and always had the most recent version number in the very first and top line, this file could also be queried by scripts to find out the most recent version ie emoncms could identify when the installed version is not up to date.
https://raw.githubusercontent.com/emoncms/dashboard/master/CHANGELOG.md
may not be as pretty as the pdf but it avoids using yet another site (gitprint) and if the “announcements” are kept up to date most users will not even need to visit github or gitprint to see the changelog.
something like
curl -s "https://raw.githubusercontent.com/emoncms/dashboard/master/CHANGELOG.md" | awk 'NR==3' | awk -F' ' '{print $2}'
will (currently) return the latest version direct from the repo, ie
v1.0.2
but this is dependent on the same format being utilized every time without fail (Had to change this just now as your latest log entry has no colon) and the easiest format to maintain is probably no formatting, it would certainly make getting the current release easier and more reliable than having a second “version” file.
I did look for a Discourse plugin to allow the raw github changelog.md to be embedded in a forum topic, but I couldn’t find anything and even if there were such a thing, it probably wouldn’t trigger an email alert, so it would be pointless.
Just throwing more ideas out there!
1 Like
Yes, there is only a master branch for the dashboard, but good point, I can see the value in having 2 branches for the dashboard., so we can accumulate and extensively test a number of changes before we merge the two and then update the version. Otherwise, we’ll quickly be up to v256.256.256!!
I think that the changelog should therefore reflect the stable deployed branch - any other thoughts on this?
Yes, agree, update information should be part of this.
Paul
EDIT - @pb66 you have replied whilst I was typing…
Yes, agree. But at the moment this does not appear to be supported by T&G
I added the title as an afterthought, because if visitors follow the link, there would be no obvious information to show which changelog that they were looking at after following the links.
As I said above, if we had 2 dashboard branches, we could group updates, merge to master/stable and copy over to the forum less frequently. I don’t think that the single master branch is the best option for versioning. I’m awaiting some feedback from T&G before creating another branch.
I have used node-red changelogs as a template, as I thought that they were tried and tested & best practice, but the door is open on what format people prefer.
The aim of the work I’ve done so far is to gather opinions, as it can easily be changed or dismantled very quickly, so thanks both.
Paul
@pb66 - quick question.
If the changelog was without format and title, would it enable the local changelog to be parsed for displaying the version number in the admin page (as per Glyn’s comment above)?
I was assuming that an additional meta file would need to be added to each of the modules, but if the version info could be obtained from the local changelog it would avoid having to update a meta file as well.
Another option could be to get the local installed version number by $ git describe --tags but maybe that would become messy?
An example of the changelog with all formatting removed would look like this.
Paul
I agree a (min) 2 branch strategy is needed for all the (emoncms family?) repos for “released” and “development” versions. I also think the branch naming should be uniform accross all the repos so that once we start to implement some form of version checking/automated updates, the branch can be set just the once rather than having to somehow accommodate a separate branch ref for each module, so that you are effectively running a whole “released” setup (default) or a complete “development” setup (advanced or devs only etc) possibly even able to switch between them.
The simpler the file is the easier it is to parse, easier to parse means less complexity, less errors and better reliability.
Ideally a simple “version” file is ideal, but to avoid maintaining 2 files I thought one file might be better, no syncing required as just one place to edit.
However, IMO there absolutely must be a file with the version easily accessible in-side the emoncms repo/folder for emoncms to have both a local(current) and on-line(latest) version to compare.
The changelog is currently being discussed as being 1) on the forum, 2) within the released “tag” notes on emoncms and also 3) within the code in the form of a changelog.md (AND possibly even on gitprint), so I question the need for an actual changelog.md file since users can view the changelog in other places, I think a “version” file is more appropriate and if we choose it can also contain some changelog, if we choose to only have the version number in the first line for easy parsing, the content and format of rest of the file can be unimportant.
But if the file did remain empty apart from the version number it would be even easier to parse, the following url would act like a proper api call
https://raw.githubusercontent.com/emoncms/<MODULE>/<BRANCH>/version
so perhaps if we must have a changelog 2 files is better than 1?
I looked into that too, and yes “messy” is a good word for it!
The more i think about it I think a choice between an in repo changelog and “tag notes” is required and just “officially” maintain the one changelog, and if one of us then decide to make an announcement on the forum that a new version has been tagged (and cut&paste the changelog text from the repo to the forum), I’m sure T&G are not going to forbid us from doing that!
Using a “closed to comments” thread that all emoncms users can subscribe to will enable users to easily stay up to date and encourage users to visit the forum following each release rather than just when things go wrong.
On that note I wonder if a main announcements category is preferable with an “emoncms-announcements” sub-category for all the emoncms repos announcement threads to reside in, that way a user can subscribe to all emoncms-announcements by subscribing to the category rather than all the individual threads. Or even to the main announcements category to include other softwares such as emonhub or emonpi in time.
As a side note, I think the naming used by emoncms/emoncms is not clear when the master branch is called “stable” and the development branch is called “master”, this conflicts with normal GitHub usage, so I would question whether those same names should be rolled out to all the other repos or if implementing this would be the ideal time to change the names on the one repo. It would not be difficult to allow a static “stable” branch to remain for a while until all users have updated, and just the emonpi script can be adjusted, once updated the branch name would be set within emoncms.
I still do not understand Git 
I was made aware of a link to latest release via Release 10.8.5 · emoncms/emoncms · GitHub but it seems that is branch agnostic.
Looking at Emoncms, I do not undertand why the stable branch seems to be ahead of the master, but I’m sure there is a reasonable explanation!
I actually wonder if Git expects the ‘master’ to be the main/stable branch and any other branch should be the development branch. I have the link some kind soul sent me a while back for a git manual - perhaps I’ll take it with me for some light holiday reading.
You are far from alone!
Indeed it is, When you download “latest” or any other tagged point in time, you are downloading the whole caboodle and you can switch between the branches.
Yep, the default branch name when there is only one branch is master, when you start adding branches, the default branch you see when going to GitHub or when you clone/download without specifying a branch is “master”. The master branch is usually considered the “main” branch if you like. But emoncms not only calls it’s main branch “stable” (which is a little presumptuous) it also calls it’s secondary (development) branch “master”, which although perfectly workable when you know about it, isn’t as obvious as it could be.
Calling one branch “dev” or “development” is crystal clear, as for a “released” production branch, “released” is clearer but “master” maybe more expected, I think I prefer “released” just to avoid any preconceived idea’s about what “master” might or might not be, but all that is really important is that it is clear and consistent.
1 Like
Wow, that’s awesome. Nice work