Changelog for symfony documentation

[shoomyth]

Is there any changelog for documentation?
How can I determine what changed since certain date when I read docs last time?
I saw notes "New in version x.x", but i have to scan all chapters for this notes.
Maybe it would be useful to create a section in docs where all changes will be tracked. And after reading the Book and Cookbook I could check this section for additions/modifications and be aware of all changes and be sure that nothing missed.

Sorry if dup, i haven't found any.

[stof]

New in version x.x are about new Symfony features, not about new documentation.

The docs are evolving a lot in many chapters. Keeping a list of all changes int eh docs themselves would be a real pain. the best way is probably to look at the git history.

[wouterj]

An example of a compare for the master branch:
https://github.com/symfony/symfony-docs/compare/master@{3.weeks.ago}...master

or for a specific date:
https://github.com/symfony/symfony-docs/compare/master@{2013.1.1}...master

[shoomyth]

Yep, git history is the first thing that comes to mind. But there are a lot of small fixes - typos, formatting and so on. And it's easy to miss important commits. Moreover I think reviewing git history for changes is too nerd :)
I agree that tracking all changes is a pain, maybe it would be possible to keep only important updates (e.g. only important changes, new chapters in cookbook).
Just suggestion for improving docs usability. It's a common docs problem - developer doesn't know about changes after first reading. And this log could help like symfony's blog

[wouterj]

I agree it's a problem, but changelogs are not the solution for this problem IMO. The only good solution I can think of now is to create a rss feed for the docs.

Why I don't think changelogs are a solution:

1. Docs are created to be rendered. The reader should never have to view the raw files to look for changes. (that's why I agree that got compares aren't great)
2. It's a pain to maintain it. It will led to (a) less time to write docs and (b) makes contributing harder (we want that to be as low as possible)

(sidenote, I usually tweet new articles, so you can follow me if you want to keep track of that)

[mahmouds]

+1 for the rss feed, Also a last updated date displayed for each document would be nice.

[wouterj]

The date is a great idea imo. I ping @fabpot, so he can give his opinion about this.

[fabpot]

I don't understand how an updated date displayed for each document would help the reader. You probably don't remember the last time you read this specific page, and it wouldn't help spot the differences since last time anyway.

As for the RSS feed, you would have all changes coming from typos as well.

To me, having a real changelog curated by the doc authors is the only valid option. We can add that as a requirement when someone submit a pull request (like what we have for the code; that's not much different).

[wouterj]

I think seeing what is changed is only usefull for people downloading the documentation. If you read the docs, you just read the quick tour and some relevant book articles the first time. After that, you only refer to the docs if you want to know a specific feature.
For both things, it isn't needed to see when it was updated IMO.

However, if you download the docs, you know you get an outdated version in a couple of weeks. You need to know if the articles you want to read are to must outdated. Then a 'updated date' is really usefull.

I agree with the feed and typos, I didn't think of that.

A changelog is still not my choice. Docs are created to be rendered, in fact nobody will see these raw ReSt files (except for all the people who contribute!). Having to go to the raw files to see what's changed is not something I like.

[mahmouds]

Well the last updated date will not help me to spot the changes done in the document but it will let me know if a document had a recent change.

For example if i see that the document last updated date was 1-4-2013 then a recent change was done to this document but if the date is 1-1-2013 it means that i probably do not need to review it.

As for the rss feed, It is not only about typos it is about typos and corrections to old code as well.
Even if it is only a typo change i still can ignore it is feed if we use categories for the rss feeds.

A change log will be too long and will also contain typos, For me -as a developer- github compare and git commits are more than enough to let me know the recent changes.

[fabpot]

@mahmouds A CHANGELOG would manually written and would not contain the typo corrections.

This is by far the best solution and should not cause a big overhead. Again, that's what we are doing for the code and it works pretty well.

[mahmouds]

I will suppose that we will have 3 change log files for each branch like symfony, Can any one tell me how to categories the changes done by time so that i can know exactly what changed in the past month ?

[gm-olivier]

Would it make any sense to have the changelog automatically extracted from the commit messages? E.g. by taking any text that follows a “CHANGLELOG” line?

[wouterj]

@gm-olivier yes, we can do something like the angularjs commit conventions. However I think that updating the changelog by hand in PR is easier to use for not-core contributors