Added a note about BC #111
Conversation
| Discovery | ||
| --------- | ||
|
|
||
| The order of which the strategies are included is not part of our BC promise. The strategies them self is marked |
There was a problem hiding this comment.
s/them self is/themselves are
|
👍 |
|
Someone please review this. I like it. |
| Discovery | ||
| --------- | ||
|
|
||
| The order of which the strategies are included is not part of our BC promise. The strategies themselves are marked |
There was a problem hiding this comment.
The order of the strategies is not part of our BC promise.
|
agree with this! i tried to simplify some of the wording, otherwise agree with it. one question: this doc is speaking in the "we" form. do we generally do that, do we want to do that? or should it be formulated more unpersonal? |
|
Thank you for the review. I did not give it much thought at the time of writing. I know that Fabrice Bernhard once said that you should never write "we" in the documentation. In our documentation we write "we" time to time. (Google search) |
|
|
||
| The order of the strategies is not part of our BC promise. The strategies themselves are marked | ||
| as ``@internal`` so they are also not part of our BC promise. | ||
| However, we do promise that we will not remove a strategy neither will we remove classes from the ` |
There was a problem hiding this comment.
the backtick at the end of this line looks like it needs to be removed
| * 1.0.0-beta10 | ||
|
|
||
| The consequences of the BC promise for the discovery library is that you can not rely on the *same* client to be | ||
| returned in the future. However, you can be sure that if discovery finds you a client now, future updates will still |
There was a problem hiding this comment.
I think I would simplify this sentence a bit:
However, if discovery does find a client now, you can be sure that after future updates it will still discover a client.
There was a problem hiding this comment.
Do you have any suggestions? I've already been corrected on that line: #111 (comment)
There was a problem hiding this comment.
I would just change the current sentence with the one I put in the blockquote in my comment. But as @dbu already commented on this before, he may want to add if here actually agrees that that would be easier to read or if he preferred to keep the current sentence.
There was a problem hiding this comment.
Sorry Christian... It was a weird comment by me.
I do like your suggestion. I hope David do not mind if I change his suggestion.
There was a problem hiding this comment.
|
i left the "we" in. its indeed in several places, and i think it fits much better in meta documentation like this than in direct technical documentation where i think we should continue to avoid it. |
This will replace php-http/discovery#77