Add backwards compatibility docs #1736
Conversation
|
I can probably figure this out somehow, but are the required code changes already merged for this? |
Which code changes you mean? |
|
|
||
| Keeping backwards compatibility has a very high priority in the pytest project. Although we have deprecated functionality over the years, most of it is still supported. All deprecations in pytest were done because simpler or more efficient ways of accomplishing the same tasks have emerged, making the old way of doing things unnecessary. | ||
|
|
||
| With the pytest 3.0 release we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around. |
There was a problem hiding this comment.
while this sentence is fun to read, my personal oppinion is that we should pick a more conservative way to say it for the documentation
my first idea for a more moring way to say it would be we will actually remove aged and outdated features to open a path for future developments
|
@flub All code changes having to do with this PR are already merged in the features branch (showing pytest warnings by default and adding the flag to silence them explicitly). @RonnyPfannschmidt I sent the text around on the mailing list last week (because I was not sure yet against what to make the PR and the original release date came rushing towards us). Feedback ranged from positive to no objections, so I opened the PR with the recommended changes. IMHO I don't see why documentation has to be boring or must not contain the odd pop cultural reference (py ... ehh pie also plays an important role in MIB, so it's actually relevant!). How about merging it and fixing it later if people complain that the docs are not boring enough anymore? |
|
I've gone with the C4 philosophy and merged :-) If we want a more "formal" tone of voice then we can do that in another PR. Is tone-of-voice a thing defined in the new docs refactoring? /cc @pfctdayelise @hackebrot |
|
im fine with that as well ^^ @obestwalter seems like i missed the mail |
|
Thanks for merging. My work is done here then :) @RonnyPfannschmidt - I guess it might have been better to open an issue for the overall change and discuss it there. I will keep that in mind for the next time. Mail for reference: http://comments.gmane.org/gmane.comp.python.pytest.devel/1429 |
|
Our docs are not up to a point of worry about tone that much IMO... Does this need to be linked in more places though? Only in the contents is pretty limited. Like the contribution guide? |
|
@pfctdayelise I just added it in the most simple way possible for now, so that it is actually there for the 3.0 release. I would think as a start in the current form it is enough like it is. For the restructured documentation I would suggest to make it part of something that describes the pytest release process (which AFAIK does not exist yet at all in the current docs). We could cut a slice from the Django docs for that: https://docs.djangoproject.com/en/1.9/internals/release-process/ - I would not mind helping with an effort to add documentation like that, which could then ideally be used in tox, devpi and pytest (if it fits all three projects). |
There is no open issue for this but it is part of the plan for the 3.0 release.
Together with the introduction of showing internal deprecation warnings by default and the possibility to explicitly silence them it completes the plan for having a transparent way of dealing with backwards incompatible changes.