{"action":"created","issue":{"url":"https://api.github.com/repos/netty/netty/issues/4121","labels_url":"https://api.github.com/repos/netty/netty/issues/4121/labels{/name}","comments_url":"https://api.github.com/repos/netty/netty/issues/4121/comments","events_url":"https://api.github.com/repos/netty/netty/issues/4121/events","html_url":"https://github.com/netty/netty/issues/4121","id":102433569,"number":4121,"title":"HttpHeaders 4.1 deprecation and consistency with master","user":{"login":"Scottmitch","id":7562868,"avatar_url":"https://avatars.githubusercontent.com/u/7562868?v=3","gravatar_id":"","url":"https://api.github.com/users/Scottmitch","html_url":"https://github.com/Scottmitch","followers_url":"https://api.github.com/users/Scottmitch/followers","following_url":"https://api.github.com/users/Scottmitch/following{/other_user}","gists_url":"https://api.github.com/users/Scottmitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Scottmitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Scottmitch/subscriptions","organizations_url":"https://api.github.com/users/Scottmitch/orgs","repos_url":"https://api.github.com/users/Scottmitch/repos","events_url":"https://api.github.com/users/Scottmitch/events{/privacy}","received_events_url":"https://api.github.com/users/Scottmitch/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/netty/netty/labels/discussion","name":"discussion","color":"fbca04"}],"state":"open","locked":false,"assignee":{"login":"Scottmitch","id":7562868,"avatar_url":"https://avatars.githubusercontent.com/u/7562868?v=3","gravatar_id":"","url":"https://api.github.com/users/Scottmitch","html_url":"https://github.com/Scottmitch","followers_url":"https://api.github.com/users/Scottmitch/followers","following_url":"https://api.github.com/users/Scottmitch/following{/other_user}","gists_url":"https://api.github.com/users/Scottmitch/gists{/gist_id}","starred_url":"https://api.github.com/users/Scottmitch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Scottmitch/subscriptions","organizations_url":"https://api.github.com/users/Scottmitch/orgs","repos_url":"https://api.github.com/users/Scottmitch/repos","events_url":"https://api.github.com/users/Scottmitch/events{/privacy}","received_events_url":"https://api.github.com/users/Scottmitch/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/netty/netty/milestones/117","html_url":"https://github.com/netty/netty/milestones/4.1.0.Beta6","labels_url":"https://api.github.com/repos/netty/netty/milestones/117/labels","id":1100817,"number":117,"title":"4.1.0.Beta6","description":"","creator":{"login":"normanmaurer","id":439362,"avatar_url":"https://avatars.githubusercontent.com/u/439362?v=3","gravatar_id":"","url":"https://api.github.com/users/normanmaurer","html_url":"https://github.com/normanmaurer","followers_url":"https://api.github.com/users/normanmaurer/followers","following_url":"https://api.github.com/users/normanmaurer/following{/other_user}","gists_url":"https://api.github.com/users/normanmaurer/gists{/gist_id}","starred_url":"https://api.github.com/users/normanmaurer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/normanmaurer/subscriptions","organizations_url":"https://api.github.com/users/normanmaurer/orgs","repos_url":"https://api.github.com/users/normanmaurer/repos","events_url":"https://api.github.com/users/normanmaurer/events{/privacy}","received_events_url":"https://api.github.com/users/normanmaurer/received_events","type":"User","site_admin":false},"open_issues":68,"closed_issues":84,"state":"open","created_at":"2015-05-07T19:29:09Z","updated_at":"2015-08-21T18:45:11Z","due_on":null,"closed_at":null},"comments":1,"created_at":"2015-08-21T18:02:48Z","updated_at":"2015-08-22T01:53:39Z","closed_at":null,"body":"The master branch has a unified class hierarchy for headers.  When this work was back-ported (PR https://github.com/netty/netty/pull/3074) we agreed to change APIs for everything but HttpHeaders/DefaultHttpHeaders (see https://github.com/netty/netty/pull/2908#issuecomment-59883796) for backwards compatibility reasons.  Recently some major rework was done to rectify performance issues, and the discrepancy between HttpHeaders/DefaultHttpHeaders in master and 4.1 was a pain point. The maintenance is currently difficult, maybe error prone, and essentially all methods in HttpHeaders/DefaultHttpHeaders have been deprecated.  How can we improve this situation:\r\n\r\n1. Can we break API in 4.1 HttpHeaders/DefaultHttpHeaders? Complexity would go down, a layer of indirection would be removed, and maintenance would be easier/less error prone.\r\n2. Should we re-analyze the recent updates in 4.1? For example should all the methods be deprecated (some with no direct replacements...bcz I don't want to have to maintain both the new and the old interface in 4.1)?\r\n\r\nI guess this brings up the bigger question of \"what is our deprecation policy?\".  The only thing I can find is http://netty.io/news/2014/12/17/changes-in-deprecation-policy.html which acknowledges a change, but does not reference any other \"original\" policy. \r\n\r\nFor this specific case it was OK to break some/most APIs, but not others. Is there a hard/fast rule on what can/cannot be broken, or is this more of a judgement call based on perceived usage and how users would react. Should we take some sort of user poll to see if the API breakage is tolerable?\r\n\r\n/cc @trustin @normanmaurer @buchgr @nmittler "},"comment":{"url":"https://api.github.com/repos/netty/netty/issues/comments/133625185","html_url":"https://github.com/netty/netty/issues/4121#issuecomment-133625185","issue_url":"https://api.github.com/repos/netty/netty/issues/4121","id":133625185,"user":{"login":"trustin","id":173918,"avatar_url":"https://avatars.githubusercontent.com/u/173918?v=3","gravatar_id":"","url":"https://api.github.com/users/trustin","html_url":"https://github.com/trustin","followers_url":"https://api.github.com/users/trustin/followers","following_url":"https://api.github.com/users/trustin/following{/other_user}","gists_url":"https://api.github.com/users/trustin/gists{/gist_id}","starred_url":"https://api.github.com/users/trustin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/trustin/subscriptions","organizations_url":"https://api.github.com/users/trustin/orgs","repos_url":"https://api.github.com/users/trustin/repos","events_url":"https://api.github.com/users/trustin/events{/privacy}","received_events_url":"https://api.github.com/users/trustin/received_events","type":"User","site_admin":false},"created_at":"2015-08-22T01:53:39Z","updated_at":"2015-08-22T01:53:39Z","body":"The original policy was the semantic versioning, as detailed in http://semver.org/ I thought it's too strict about deprecation and the removal of the deprecated API, so I changed the deprecation policy, but the basic principle remains same. e.g. 4.1.x JAR should be a drop-in replacement of 4.0.x JAR as long as a user did not use the deprecated API, did not use our API in an unusual way, and did not touch our internal API.\r\n\r\n> Can we break API in 4.1 HttpHeaders/DefaultHttpHeaders?\r\n\r\nNo? \r\n\r\n> Should we re-analyze the recent updates in 4.1?\r\n\r\nI'm not sure. It would be easy to decide to deprecate the methods with replacements. If there's no replacement, I would document it properly - why it's deprecated without replacement. Of course I wouldn't deprecate it if there's no good reason.\r\n\r\n> For this specific case it was OK to break some/most APIs, but not others.\r\n\r\nIIUC, the classes that changed without backward compatibility did not exist in 4.0, so we can make any changes until we release 4.1.0.Final. I don't think we didn't break any rule here therefore.\r\n\r\nHere's what I think (and @normanmaurer as well I guess):\r\n\r\n- We basically employ semver + relaxed deprecation policy.\r\n- However, we are not dogmatic about it; we might break the API when we are pretty sure usual users are not surprised.  Changing most public API will be surprising in most cases, so we should be very careful. Here are some changes which might be fine:\r\n  - Changes that might affect transport implementations, such as:\r\n    - Changing some protected methods in `AbstractChannel`\r\n    - Changing the `Unsafe`\r\n  - Changes under the `internal` package\r\n  - Experimental modules like spdy (this isn't experimental anymore though.)\r\n\r\nWDYT?"}}