Add docs for deprecated functions about momentjs.com HOT 3 CLOSED

Perhaps we need to establish a deprecation policy for functionality? It would be a pretty bad surprise if a certain piece of functionality just disappeared without notice. Do you think one minor release number between notice of deprecation and removal of functionality is enough?

Additionally, I think the documentation for the deprecated feature should stay up, but only to explain how to update code or to work around the missing feature.

What do you think?

from momentjs.com.

Yeah, I think 1 minor release should be enough time. It tends to be about a month and a half or so between releases. Do you think it's too late now to deprecate for 1.6? 1.5 released March 19, so if we get the docs up now, it will be about month until the 1.6 release.

I think we should also make upgrade path notes either on the changelog on the github readme, or in the docs themselves. The only communication we have are those and the twitter account, but the twitter account has very few followers, so that's not really reliable.

You can see an example of the upgrade notes I added in the past on the readme here https://github.com/timrwood/moment/tree/0.6.0

from momentjs.com.

I think that since we've already removed some functionality, let's go ahead and leave it removed in 1.6, but I think if we remove any more functionality, that it should still work until 1.7. Does that sound good?

I would probably look at the changelog for upgrade paths actually. I don't think Twitter is a viable place to put upgrade paths, especially because I'm in China right now. :)

from momentjs.com.