Guide changelog
Closed this issue · 18 comments
The guide seems like a living and everevolving set of articles.
But during course of life, one can very easily miss what's new and what's changed on this guide.
For example, having read through the guide earlier, I've concentrated on the sections around application structure and react. And then missed a great section about code style even though it was right there before my eyes.
@stubailo yes I'm referring to our discussion around my silly little PR.
So it would be great if there were a changelog.md or even better yet, tagged releases that summarize the changes.
Ah great that we have an issue now! I don't really like the idea of tagged releases because I think the guide should be ever-changing (do we really need version numbers for this thing??).
I'd maybe just do a changelog by date, like "2016/03/08: added this and this"
My feeling is the migration article is enough (see this bit: http://guide.meteor.com/1.3-migration.html#guide)
If we make significant changes to the guide between Meteor releases, this won't be enough, but I don't see that happening, TBH
Honestly, I dismissed the migration article because it is named as "migration" and I don't have an app that I want to migrate. So I skipped it altogether.
I know you have a right the say RTFM but you should agree that "migration" is not the best choice of words for a document that should represent the differences in two states of some document.
Furthermore, the guide is everevolving and will most probably see updates without any actual meteor release changes. I would like to be able to see a brief overview without consulting "migration" topics or commit history.
Maybe it can be an opt-in kind of thing, where you only add to the changelog on a major change? Alternatively, we can just rename the migration article to "changes in 1.3" or something.
I think changes in 1.3 could actually a better name, but still does not fully address my initial concern.
The book's premise is not Meteor's official core releases. It has always been advertised as much wider than that. It includes best practices, community contributions etc. In fact, the content based around this hollistic approach itself has been advertised to be the core.
Therefore it is very likely that the content of the guide will get updated more ofthen than meteor's core updates. No?
This calls for either constantly keeping an eye on the guide, or a mechanism that is contained within the guide itself, hence my suggestion for a changelog.
If however, the guide will not see any updates in between meteor core releases, then that calls for a different discussion.
Therefore it is very likely that the content of the guide will get updated more often than meteor's core updates. No?
I think the idea is that we want to make Meteor releases much, much, much more frequent (think weeks not months). And in that case aligning major updates to the guide with new releases kind of makes sense. For example, if we are going to be switching a recommendation from Flow Router to something else (just an example) that would be a release-worthy change since it would be a huge shift in how people should be writing their apps.
But of course in between those we'll accept PRs for changes of varying significance, and you're right that it's hard to keep track of these changes since the git commit log isn't a good way to do that.
So I would be in favor of a changelog.
My biggest concern is making it too hard to contribute content to the guide, because there is all this overhead of updating the changelog, etc. But if we only require changelog items for significant changes beyond just fixing errors and typos, then I wouldn't be worried about it.
But if we only require changelog items for significant changes beyond just fixing errors and typos, then I wouldn't be worried about it.
I agree. I would not expect a changelog to be crowded with relatively insignificant changes. After all, the point is to understand what parts of the guide are actually worth re-reading.
Thanks
OK the next step is setting up a contribution guide and creating a blank changelog file.
I think the root readme.md is essentially the contribution guide.
Otherwise, I would need a contribution guide to contributing to the contribution guide guide which would be so meta my head is already spinning right now ;)
Yeah that's a good point! The README is enough. Should the changelog just go in there as well, or should we have a changelog file/article?
I've seen both. I guess a section at the end of the readme could suffice for the moment and in time, as it grows, we could separate it as you guys see it fit.
There's a changelog now!
https://github.com/meteor/guide#changelog
I'd love to accept suggestions about how it should work and how it can be better formatted, but seems to be working for now!
Wow just spotted that myself, thank you, this is really great!
Do you think we could also integrate that with the guide itself in such a way that we don't need to do back and forth with the github readme?
Hmm we could make it one of the pages! For the table of contents we would probably put it under "migrating to 1.3"?
Yeah, I guess I did not think it through when I first said "a section at the end of the readme could suffice"
Re placement, some of those changes are/will be post-1.3 so it may be misleading.
Is there perhaps other "meta" information that we'd like placed within the published guide? They can be combined into their section/subsection somewhere.
Oh, by "under" I meant, not in the same article, but in a new entry beneath it. So it wouldn't look like the same thing.
OK, I think I've definitively resolved this issue:
- contributing: https://github.com/meteor/guide/blob/master/CONTRIBUTING.md
- changelog: https://github.com/meteor/guide/blob/master/CHANGELOG.md
Both are also on the live site:
Wow! choice of wording (meta) is also great! Thanks for taking the time to make this happen.