Normalize special CouchDB headers names

[kxepal]

COUCHDB-2353

[kxepal]

If the solution is ok, I'll open few more PRs against chttpd, replicator and mrview.

[kxepal]

This obliviously breaks backward compatibility, but 2.0 is a good time to cleanup and normalize stuff.

[davisp]

Do we want to worry about backwards compatibility here or not? Or maybe we can add a check that throws a 400 if it detects an old header name? This just feels like one of those places where people will get frustrated when something doesn't work like it used to without any feedback or indication of what exactly changed.

[kxepal]

@davisp I found myself more frustrated because special headers are don't follows some single logic and I have always consult myself with docs to be sure that I name it right (since CouchDB will just ignore unknown header).

As for backward compatibility point, it only matters for replicator which uses X-Couch-Full-Commit to force CouchDB accept new docs with delayed_commits on. I believe, this isn't what we want to let him doing, but that's another story.

[davisp]

@kxepal Sure, I agree that normalizing things to be consistent is a good idea. I'm just saying that for any user that happens to miss this particular change in the log will have a very bad experience figuring the change out. If we instead detected the presence of old headers and returned a 400 Bad Request we could inform them directly that the header names have changed. Alternatively we could upgrade old header names though in the interest of deprecating I'd prefer the 400 I think.

[janl]

Can we please stop the meme of “we are bumping the major version so let’s break everything.”?

We should be very deliberate with what we break and when, in order to avoid a Python 3 situation. From my post on dev@ earlier today on the delayed_commits thread:

One of my goals for CouchDB 2.0 is that people upgrading form 1.0 and
especially people who continue use CouchDB in a single-node scenario
have an easy time. Just breaking more things because we happen to be
bumping a version number is not a good motivation. Especially in our
new world of avoiding attaching marketing connotation to major release
versions (except 2.0 :), we can release CouchDB 3.0 and 4.0 shortly
after 2.0 if it means we break BC in a single way. If we keep BC breaks
to a minimum and make every transition up a major version as easy as
possible, we don’t run into a Python 3 situation that creates a major
schism in the user community that takes a decade to heal.

Let’s not break things because we update the major version number,
instead, let’s update the major version number whenever we break
back backward compatibility.

---

I do like the idea of detecting the “wrong” case and logging an error so people have a chance to upgrade it. Maybe also send an x-couch-deprecation-notice header with an URL to the docs where it is explained.

---

-1 on breaking BC for this without a plan.

(sorry @kxepal :)

[kxepal]

Maybe also send an x-couch-deprecation-notice header with an URL to the docs where it is explained.

We'd already discussed this moment: nobody will look and process this header to be notified about.

Can we please stop the meme of “we are bumping the major version so let’s break everything.”?

Question not about breaking everything in the name of major version bump, but cleanup existed things. What you suggests (we can release CouchDB 3.0 and 4.0 shortly) has own drawback side: people wouldn't use our releases because we minory breaking things too often to support any of these versions and they will wait until we stop doing this. So it's about of choice of lesser evil: break more at once or break by a little for many times. I, as a user, agreed to suffer BC releases as far as this would be rare thing no matter how much stuff is broken - until migration process and alternatives will be well documented and will not require a lot of work to maintain compatibility of multiple (or two at least) major releases.

And I just proposed this change to trigger the discussion about how handle it right (: @davisp suggested good idea with 400 response, so users will be alerted about using old stuff for new environment. More ideas are welcome (:

[janl]

Maybe also send an x-couch-deprecation-notice header with an URL to the docs where it is explained.

We'd already discussed this moment: nobody will look and process this header to be notified about.

Then maybe not :) — I know I’d be looking at it, but that’s not representative.

break more at once or break by a little for many times

I’ve only seen the latter work satisfactory. But that’s my personal bubble :)

Thanks for getting the discussion rolling!

---

I think at some point we generally agreed on this process:

1. Version N: Has feature X
2. Version N+1: Feature X gets a deprecation warning (release notes, logs etc.) / handles the new and old case gracefully (if possible)
3. Version N+2: Feature X gets removed

So in this case, I’d say:

1. CouchDB 1.0 has this feature
2. CouchDB 2.0:
   • accepts both the fixed and the existing notations (like we did with the authentification config value or header, I forget)
   • prints warning (say in the logs), when the old notation is used
   • release notes carry deprecation warning
3. CouchDB 3.0 sends 400 error on the old notation and just works on the new one. The change is made.

[kxepal]

1. Version N: Has feature X
2. Version N+1: Feature X gets a deprecation warning (release notes, logs etc.) / handles the new and old case gracefully (if possible)
3. Version N+2: Feature X gets removed

Good idea and well balanced. I like it (: Will rewrite my PR to match it.