search

silverstripe / doc.silverstripe.org

The source code that powers http://doc.silverstripe.org
BSD 3-Clause "New" or "Revised" License
14 stars 19 forks source link

Changelogs? #10

Closed wilr closed 10 years ago

wilr commented 12 years ago

This was brought up by @halkyon and me having a chat about the changelog docs being out of date and it got me thinking, what's the reason we have the changelogs on the wiki? They don't actually get updated ever after they're created.. We do a number of things to reduce the changelogs being shown in the search and it can get annoying doing a global search in my editor to sift through the changelogs.

Perhaps a better way would be to publish the changelogs to silverstripe.org/changelogs and simply leave the documentation for upgrade 'notes' on each version and how tos rather than just a git log.

Thoughts?

sminnee commented 11 years ago

It sounds like what you want to do is exclude the changelogs from the search? That makes sense. I don't see any motivation for moving them from where they are apart from that?

wilr commented 11 years ago

Duplicate URLs is the big one. And appearing in project when using global search (locally). Figure by publishing them on silverstripe.org might also make them more 'official' then wiki content.

sminnee commented 11 years ago

They're on doc.silverstripe.org, which isn't a wiki - it's based on the official repository of the project.

sminnee commented 11 years ago

I suggest that we fix the URLs situation, maintaining a single URL for the changelog, rather than a version-specific thing. And we remove them from search. But that we keep the changelogs where they are.

chillu commented 11 years ago

I've gone back and forward on this one a couple of times, and I think the benefits of having a changelog built up alongside the code commits in source control outweighs the disadvantages of them being part of the release process. Having a single URL for all changelog info on a specific release is definitely useful.

Repository size is another consideration, framework/docs/en/changelogs is a whopping 1.8MB when uncompressed, and still 0.5MB gzipped. So a lot of stuff which needs to be transferred on a git clone (which is my primary concern). Not that we can change that after the fact (the one thing I hate about git), but it'll get worse over time. Every changelog adds about 30kb. BTW, this is irrelevant for "composer create-project " and ZIP downloads since we can exclude /docs from there.

So, overall I would suggest that we remove the "other changes" bit, so anything that's not "API", "NEW", or "BUG", and replace it with links to github log views on sapphire, installer and cms. That should save about a third of the space.

In terms of search in IDE, simply limit your search to *.php :) Or of searching for docs, use doc.ss.org.

We could also introduce a special [commit] tag in doc.ss.org which would auto-expand URLs to github.com, saving more space.