<html><head></head><body><div>On Wed, 2020-12-30 at 11:43 -0600, Sebastian Berg wrote:</div><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><div>On Wed, 2020-12-30 at 16:27 +0100, Ralf Gommers wrote:</div></blockquote><div><snip></div><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><div><br></div><div>That's very hard to describe, since it relies so much on previous</div><div>experience and qualitative judgements. That's the main reason why I</div><div>had</div><div>more examples before, but they just led to more discussion about</div><div>those</div><div>examples - so that didn't quite have the intended effect.</div></blockquote></blockquote><div><snip></div><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><div>I only took a short course and used this very little. I am sure there</div><div>are many here with industry experience where the use of Q&A is every</div><div>day work.</div><div><br></div><div><br></div><div>One concept from there is to create a risk/danger and probability</div><div>assessment, which can be ad-hoc for your product. An example just to</div><div>make something up:</div></blockquote><div><br></div><div><br></div><div>I am not sure anyone finds this interesting or if fits to the NEP specifically [1], but I truly think it can be useful (although maybe it doesn't need to be formalized). So I fleshed it out: <a href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw">https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw</a> (also pasted it below)</div><div><br></div><div>My reasoning for suggesting it is that a process/formalism (no matter how ridiculous it may seem at first) for how to assess the impact of a backward compatible change can be helpful by: conceptualizing, clearly separating backward incompatible impact assessment from benefits assessment, making it easier to follow a decision/thought processes, and allowing some nuance [2].</div><div><br></div><div>I actually believe that it can help with difficult decisions, even if only applied occasionally, and that it is not a burden because it provides fairly steps. Will it be useful often? Maybe not. But every time there is a proposal and we pause and hesitate because it is unclear whether it is worth the backcompat impact, I think this can provide a way to discuss it and come to a decision as objectively as possible. (And no, I do not think that any of the categories or mitigation strategies are an exact science.)</div><div><br></div><div>Cheers,</div><div><br></div><div>Sebastian</div><div><br></div><div><br></div><div>[1] This is additional to the proposed promises such as a two releases of deprecations and discussing most/all deprecations on the mailing list, which are unrelated. It is rather to provide a formalism where currently only the examples give points of reference.</div><div>[2] There is a reason that also the Python version is short and intentionally fuzzy: <a href="https://www.python.org/dev/peps/pep-0387/">https://www.python.org/dev/peps/pep-0387/</a> and <a href="https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421">https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421</a> There are just few definite rules that can be formalized, so a framework for diligent assessment seems the best we can do (if we want to).</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><h2 class="part" data-startline="3" data-endline="4" id="Assessing-impact" data-id="Assessing-impact" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.5em; padding-bottom: 0.3em; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: rgb(238, 238, 238); caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><span data-position="204" data-size="16" style="box-sizing: border-box;">Assessing impact</span></h2><div><span data-position="239" data-size="111" style="box-sizing: border-box;">Here “impact” means how unmodified code may be negatively affected by a change ignoring any deprecation period.</span></div><div><br></div><div><span data-position="352" data-size="142" style="box-sizing: border-box;">To get an idea about how much impact a change has, try to list all potential impacts. This will often be just a single item (user of function<span class="Apple-converted-space"> </span></span><code data-position="495" data-size="1" style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 13.600000381469727px; padding: 0.2em 0px; color: inherit !important; background-color: rgba(0, 0, 0, 0.04); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px;">x</code><span data-position="497" data-size="24" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>has to replace it with<span class="Apple-converted-space"> </span></span><code data-position="522" data-size="1" style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 13.600000381469727px; padding: 0.2em 0px; color: inherit !important; background-color: rgba(0, 0, 0, 0.04); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px;">y</code><span data-position="524" data-size="44" style="box-sizing: border-box;">), but it could be multiple different ones.<span class="Apple-converted-space"> </span></span><em data-position="568" data-size="0" style="box-sizing: border-box;"><span data-position="569" data-size="5" style="box-sizing: border-box;">After</span></em><span data-position="575" data-size="128" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>listing all potential impacts rank them on the following two scales (do not yet think about how to make the transition easier):</span></div><ol class="part" data-startline="10" data-endline="21" data-position="705" data-size="0" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="10" data-endline="15" data-position="708" data-size="0" style="box-sizing: border-box;"><div><strong data-position="708" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="710" data-size="8" style="box-sizing: border-box;">Severity</span></strong><span data-position="720" data-size="46" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>(How bad is the impact for an affected user?)</span></div><ul style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px; padding-left: 2em;"><li class="" data-startline="11" data-endline="11" data-position="773" data-size="0" style="box-sizing: border-box;"><span data-position="773" data-size="191" style="box-sizing: border-box;">Minor: A performance regression or change in (undocumented) warning/error category will fall here. This type of change would normally not require a deprecation cycle or special consideration.</span></li><li class="" data-startline="12" data-endline="12" data-position="971" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="971" data-size="139" style="box-sizing: border-box;">Typical: Code must be updated to avoid an error, the update is simple to do in a way that works both on existing and future NumPy versions.</span></li><li class="" data-startline="13" data-endline="13" data-position="1117" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="1117" data-size="76" style="box-sizing: border-box;">Severe: Code will error or crash, and there is no simple work around or fix.</span></li><li class="" data-startline="14" data-endline="15" data-position="1200" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="1200" data-size="143" style="box-sizing: border-box;">Critical: Code returns incorrect results. A change requiring massive effort may fall here. A hard crash (e.g. segfault) in itself is typically<span class="Apple-converted-space"> </span></span><em data-position="1343" data-size="0" style="box-sizing: border-box;"><span data-position="1344" data-size="3" style="box-sizing: border-box;">not</span></em><span data-position="1348" data-size="10" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>critical.</span></li></ul></li><li class="" data-startline="16" data-endline="21" data-position="1363" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><div><strong data-position="1363" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="1365" data-size="10" style="box-sizing: border-box;">Likelihood</span></strong><span data-position="1377" data-size="41" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>(How many users does the change affect?)</span></div><ul style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px; padding-left: 2em;"><li class="" data-startline="17" data-endline="17" data-position="1425" data-size="0" style="box-sizing: border-box;"><span data-position="1425" data-size="236" style="box-sizing: border-box;">Rare: Change has very few impacted users (or even no known users after a code search). The normal assumption is that there is always someone affected, but a rarely used keyword argument of an already rarely used function will fall here.</span></li><li class="" data-startline="18" data-endline="18" data-position="1668" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="1668" data-size="148" style="box-sizing: border-box;">Limited: Change is in a rarely used function or function argument. Another possibility is that it affects only a small group of very advanced users.</span></li><li class="" data-startline="19" data-endline="19" data-position="1823" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="1823" data-size="80" style="box-sizing: border-box;">Common: Change affects a bigger audience or multiple large downstream libraries.</span></li><li class="" data-startline="20" data-endline="21" data-position="1910" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="1910" data-size="59" style="box-sizing: border-box;">Ubiquitous: Change affects a large fraction of NumPy users.</span></li></ul></li></ol><div><span data-position="1971" data-size="136" style="box-sizing: border-box;">The categories will not always be perfectly clear. That is OK. Rather than establishing precise guidelines, the purpose is a structured<span class="Apple-converted-space"> </span></span><em data-position="2107" data-size="0" style="box-sizing: border-box;"><span data-position="2108" data-size="9" style="box-sizing: border-box;">processes</span></em><span data-position="2118" data-size="22" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>that can be reviewed.</span><span class="Apple-converted-space"> </span><span data-position="2141" data-size="292" style="box-sizing: border-box;">When the impact is exceptionally difficult to assess, it is often feasible to try a change on the development branch while signalling willigness to revert it. Downstream libraries test against it (and the release candidate) which gives a chance to correct an originally optimistic assessment.</span></div><div><br></div><div><span data-position="2435" data-size="75" style="box-sizing: border-box;">After assessing each impact, it will fall somewhere on the following table:</span></div><table class="part" data-startline="27" data-endline="32" style="box-sizing: border-box; border-spacing: 0px; border-collapse: collapse; background-color: transparent; margin-top: 0px; margin-bottom: 16px; display: block; width: 728px; overflow: auto; word-break: keep-all; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><thead style="box-sizing: border-box;"><tr style="box-sizing: border-box; background-color: rgb(255, 255, 255); border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204);"><th style="box-sizing: border-box; padding: 6px 13px; text-align: left; font-weight: bold; border: 1px solid rgb(221, 221, 221);"><span data-position="2513" data-size="19" style="box-sizing: border-box;">Severity\Likelyhood</span></th><th style="box-sizing: border-box; padding: 6px 13px; text-align: left; font-weight: bold; border: 1px solid rgb(221, 221, 221);"><span data-position="2535" data-size="4" style="box-sizing: border-box;">Rare</span></th><th style="box-sizing: border-box; padding: 6px 13px; text-align: left; font-weight: bold; border: 1px solid rgb(221, 221, 221);"><span data-position="2542" data-size="7" style="box-sizing: border-box;">Limited</span></th><th style="box-sizing: border-box; padding: 6px 13px; text-align: left; font-weight: bold; border: 1px solid rgb(221, 221, 221);"><span data-position="2552" data-size="6" style="box-sizing: border-box;">Common</span></th><th style="box-sizing: border-box; padding: 6px 13px; text-align: left; font-weight: bold; border: 1px solid rgb(221, 221, 221);"><span data-position="2561" data-size="10" style="box-sizing: border-box;">Ubiquitous</span></th></tr></thead><tbody style="box-sizing: border-box;"><tr style="box-sizing: border-box; background-color: rgb(255, 255, 255); border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204);"><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><strong data-position="2631" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="2633" data-size="5" style="box-sizing: border-box;">Minor</span></strong></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2646" data-size="2" style="box-sizing: border-box;">ok</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2652" data-size="2" style="box-sizing: border-box;">ok</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2658" data-size="3" style="box-sizing: border-box;">ok?</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"></td></tr><tr style="box-sizing: border-box; background-color: rgb(248, 248, 248); border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204);"><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><strong data-position="2665" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="2667" data-size="7" style="box-sizing: border-box;">Typical</span></strong></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2680" data-size="3" style="box-sizing: border-box;">ok?</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2698" data-size="3" style="box-sizing: border-box;">no?</span></td></tr><tr style="box-sizing: border-box; background-color: rgb(255, 255, 255); border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204);"><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><strong data-position="2702" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="2704" data-size="6" style="box-sizing: border-box;">Severe</span></strong></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2729" data-size="3" style="box-sizing: border-box;">no?</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2735" data-size="2" style="box-sizing: border-box;">no</span></td></tr><tr style="box-sizing: border-box; background-color: rgb(248, 248, 248); border-top-width: 1px; border-top-style: solid; border-top-color: rgb(204, 204, 204);"><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><strong data-position="2738" data-size="0" style="box-sizing: border-box; font-weight: 700;"><span data-position="2740" data-size="8" style="box-sizing: border-box;">Critical</span></strong></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2753" data-size="3" style="box-sizing: border-box;">no?</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2759" data-size="2" style="box-sizing: border-box;">no</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2765" data-size="2" style="box-sizing: border-box;">no</span></td><td style="box-sizing: border-box; padding: 6px 13px; border: 1px solid rgb(221, 221, 221);"><span data-position="2771" data-size="2" style="box-sizing: border-box;">no</span></td></tr></tbody></table><div><span data-position="2774" data-size="472" style="box-sizing: border-box;">Note that all changes should normally follow the two release deprecation warning policy (except “minor” ones). The “no” fields means a change is clearly unacceptable, although a NEP can always overrule it. This table only assesses the “impact”. It does not assess how the impact compares to the benefits of the proposed change. This must be favourable no matter how small the impact is. However, by assessing the impact, it will be easier to weigh it against the benefit.</span><span class="Apple-converted-space"> </span><span data-position="3247" data-size="152" style="box-sizing: border-box;">(Note that the table is not symmetric. An impact with “critical” severity is unlikely to be considered even when no known users are impacted.)</span></div><h3 class="part" data-startline="37" data-endline="37" id="Mitigation-and-arguing-of-benefits" data-id="Mitigation-and-arguing-of-benefits" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.25em; caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Mitigation-and-arguing-of-benefits" title="Mitigation-and-arguing-of-benefits" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="3405" data-size="34" style="box-sizing: border-box;">Mitigation and arguing of benefits</span></h3><div><span data-position="3441" data-size="188" style="box-sizing: border-box;">Any change falling outside the “ok” fields requires careful consideration. When an impact is larger, you can try to mitigate it and “move” on the table. Some possible reasons for this are:</span></div><ul class="part" data-startline="40" data-endline="45" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="40" data-endline="40" data-position="3632" data-size="0" style="box-sizing: border-box;"><span data-position="3632" data-size="173" style="box-sizing: border-box;">A avoidable warning for at least two releases (the policy for any change that modifies behaviour) reduces a change one category (usually from “typical” to “minor” severity).</span></li><li class="" data-startline="41" data-endline="41" data-position="3808" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="3808" data-size="113" style="box-sizing: border-box;">The severity category may be reduced by creating an easy work around (i.e. to move it from “sever” to “typical”).</span></li><li class="" data-startline="42" data-endline="42" data-position="3924" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="3924" data-size="56" style="box-sizing: border-box;">Sometimes a change may break working code, but also fix<span class="Apple-converted-space"> </span></span><em data-position="3980" data-size="0" style="box-sizing: border-box;"><span data-position="3981" data-size="8" style="box-sizing: border-box;">existing</span></em><span data-position="3990" data-size="106" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>bugs, this can offset the severity. In extreme cases, this may warrant classifying a change as a bug-fix.</span></li><li class="" data-startline="43" data-endline="43" data-position="4099" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="4099" data-size="126" style="box-sizing: border-box;">For particularly noisy changes (i.e. ubiquitous category) considering fixing downstream packages, delay the warning (or use a<span class="Apple-converted-space"> </span></span><code data-position="4226" data-size="25" style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 13.600000381469727px; padding: 0.2em 0px; color: inherit !important; background-color: rgba(0, 0, 0, 0.04); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px;">PendingDeprecationWarning</code><span data-position="4252" data-size="149" style="box-sizing: border-box;">). Simply prolonging the the deprecation period is also an option. This reduces how many users struggle with the change and smoothens the transition.</span></li><li class="" data-startline="44" data-endline="45" data-position="4404" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="4404" data-size="182" style="box-sizing: border-box;">Exceptionally clear documentation and communication could be used to ensure that the impact is more acceptable. This may not be enough to move a “category” by itself, but also helps.</span></li></ul><div><span data-position="4588" data-size="47" style="box-sizing: border-box;">After mitigation, the benefits can be assessed:</span></div><ul class="part" data-startline="48" data-endline="49" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="48" data-endline="49" data-position="4639" data-size="0" style="box-sizing: border-box;"><span data-position="4639" data-size="266" style="box-sizing: border-box;">Any benefit of the change can be argued to “offset” the impact. If this is necessary, a broad community discussion on the mailing list is required. It should be clear that this does not actually “mitigate” the impact but rather argues that the benefit outweighs it.</span></li></ul><div><span data-position="4907" data-size="439" style="box-sizing: border-box;">These are not a fixed set of rules, but provide a framework to assess and then try to mitigate the impact of a proposed change to an acceptable level. Arguing that a benefit can overcome multiple “impact” categories will require exceptionally large benefits, and most likely a NEP. For example a change with an initial impact classification of “severe” and “ubiquitous” is unlikely to even be considered unless the severity can be reduced.</span></div><div><span data-position="5348" data-size="504" style="box-sizing: border-box;">Many deprecations will fall somewhere below or equal to a “typical and limited” impact (i.e. removal of an uncommon function argument). They recieve a deprecation warning to make the impact acceptable with a brief discussiong that the change itself is worthwhile (i.e. the API is much cleaner afterwards). Any more disruptive change requires broad community discussion. This needs at least a discussion on the NumPy mailing list and it is likely that the person proposing it will be asked to write a NEP.</span></div><h3 class="part" data-startline="54" data-endline="54" id="Summary-and-reasoning-for-this-processess" data-id="Summary-and-reasoning-for-this-processess" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.25em; caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Summary-and-reasoning-for-this-processess" title="Summary-and-reasoning-for-this-processess" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="5858" data-size="41" style="box-sizing: border-box;">Summary and reasoning for this processess</span></h3><div><span data-position="5901" data-size="83" style="box-sizing: border-box;">The aim of this process and table is to provide a loose formalism with the goal of:</span></div><ul class="part" data-startline="57" data-endline="67" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="57" data-endline="63" data-position="5987" data-size="0" style="box-sizing: border-box;"><em data-position="5987" data-size="0" style="box-sizing: border-box;"><span data-position="5988" data-size="10" style="box-sizing: border-box;">Diligence:</span></em><span data-position="5999" data-size="157" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>Following this process ensures detailed assessment of its impact without being distracted by the benefits. This is achieved by following well defined steps:</span><ol data-position="6159" data-size="0" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px; padding-left: 2em;"><li class="" data-startline="58" data-endline="58" data-position="6162" data-size="0" style="box-sizing: border-box;"><span data-position="6162" data-size="44" style="box-sizing: border-box;">Listing each potential impact (usually one).</span></li><li class="" data-startline="59" data-endline="59" data-position="6212" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="6212" data-size="23" style="box-sizing: border-box;">Assessing the severity.</span></li><li class="" data-startline="60" data-endline="60" data-position="6241" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="6241" data-size="25" style="box-sizing: border-box;">Assessing the likelihood.</span></li><li class="" data-startline="61" data-endline="61" data-position="6272" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="6272" data-size="59" style="box-sizing: border-box;">Discussing what steps are/can be taken to lower the impact<span class="Apple-converted-space"> </span></span><em data-position="6331" data-size="0" style="box-sizing: border-box;"><span data-position="6332" data-size="21" style="box-sizing: border-box;">ignoring any benefits</span></em><span data-position="6354" data-size="1" style="box-sizing: border-box;">.</span></li><li class="" data-startline="62" data-endline="62" data-position="6361" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="6361" data-size="99" style="box-sizing: border-box;">If the impact is not low at this point, this should prompt considering and listing of alternatives.</span></li><li class="" data-startline="63" data-endline="63" data-position="6466" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="6466" data-size="130" style="box-sizing: border-box;">Argue that the benefits outweigh the remaining impact. (This is a distinct step: the original impact assessment stands as it was.)</span></li></ol></li><li class="" data-startline="64" data-endline="64" data-position="6599" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><em data-position="6599" data-size="0" style="box-sizing: border-box;"><span data-position="6600" data-size="13" style="box-sizing: border-box;">Transparency:</span></em><span data-position="6614" data-size="142" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>Using this process for difficult decisions makes it easier for the reviewer and community to follow how a decision was made and criticize it.</span></li><li class="" data-startline="65" data-endline="65" data-position="6759" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><em data-position="6759" data-size="0" style="box-sizing: border-box;"><span data-position="6760" data-size="7" style="box-sizing: border-box;">Nuance:</span></em><span data-position="6768" data-size="194" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>When the it is clear that an impact is larger than typical with will prompt more care and thought. In some cases it may also clarify that a change is lower impact than expected on first sight.</span></li><li class="" data-startline="66" data-endline="67" data-position="6965" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><em data-position="6965" data-size="0" style="box-sizing: border-box;"><span data-position="6966" data-size="11" style="box-sizing: border-box;">Experience:</span></em><span data-position="6978" data-size="148" style="box-sizing: border-box;"><span class="Apple-converted-space"> </span>Using a similar formalism for many changes makes it easier to learn from past decisions by providing an approach to compare and conceptualize them.</span></li></ul><div><span data-position="7128" data-size="291" style="box-sizing: border-box;">We aim to follow these steps in the future for difficult decisions. In general, any reviewer and community member may ask for this process to be followed for a proposed change, if the change is difficult, it will be worth the effort. If it is very low impact it will be quick to clarify why.</span></div><div><span data-position="7421" data-size="79" style="box-sizing: border-box;">NOTE: At this time the process is new and is expected to require clarification.</span></div><h2 class="part" data-startline="73" data-endline="74" id="Examples" data-id="Examples" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.5em; padding-bottom: 0.3em; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: rgb(238, 238, 238); caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Examples" title="Examples" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="7503" data-size="8" style="box-sizing: border-box;">Examples</span></h2><div><span data-position="7522" data-size="206" style="box-sizing: border-box;">It should be stressed again, that the categories will rarely be clear and intentially are categorized with some uncertainty below. Even unclear categories can help in forming a more clear idea of a change.</span></div><h3 class="part" data-startline="78" data-endline="78" id="Histogram" data-id="Histogram" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.25em; caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Histogram" title="Histogram" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="7734" data-size="9" style="box-sizing: border-box;">Histogram</span></h3><div><span data-position="7745" data-size="196" style="box-sizing: border-box;">The “histogram” example doesn’t really add much with respect to this process. But noting the duplicate effort/impact would move probably move it into a more severe category than most deprecations.</span><span class="Apple-converted-space"> </span><span data-position="7942" data-size="107" style="box-sizing: border-box;">That makes it a more difficult decision and indicates that careful thought should be spend on alternatives.</span></div><h3 class="part" data-startline="83" data-endline="83" id="Integer-indexing-requirement" data-id="Integer-indexing-requirement" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.25em; caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Integer-indexing-requirement" title="Integer-indexing-requirement" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="8055" data-size="28" style="box-sizing: border-box;">Integer indexing requirement</span></h3><ul class="part" data-startline="85" data-endline="87" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="85" data-endline="85" data-position="8087" data-size="0" style="box-sizing: border-box;"><span data-position="8087" data-size="84" style="box-sizing: border-box;">Severity: Typical–Severe (although fairly easy, users often had to do many changes)</span></li><li class="" data-startline="86" data-endline="87" data-position="8174" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="8174" data-size="22" style="box-sizing: border-box;">Likelihood: Ubiquitous</span></li></ul><div><span data-position="8198" data-size="189" style="box-sizing: border-box;">How ubiquitous it really was became probably only clear after the (rc?) release. The change would now probably go through a NEP as it initially falls into the lower right part of the table.</span><span class="Apple-converted-space"> </span><span data-position="8388" data-size="60" style="box-sizing: border-box;">To get into the “acceptable” part of the table we note that:</span></div><ol class="part" data-startline="91" data-endline="93" data-position="8450" data-size="0" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="91" data-endline="91" data-position="8453" data-size="0" style="box-sizing: border-box;"><span data-position="8453" data-size="66" style="box-sizing: border-box;">Real bugs were caught in the processes (argued to reduce severity)</span></li><li class="" data-startline="92" data-endline="93" data-position="8523" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="8523" data-size="127" style="box-sizing: border-box;">The deprecation was delayed and longer than normally (argued to mitigate the number of affected users by giving much more time)</span></li></ol><div><span data-position="8652" data-size="142" style="box-sizing: border-box;">Even with these considerations, it still has a larger impact and clearly requires careful thought and community discussion about the benefits.</span></div><h3 class="part" data-startline="97" data-endline="97" id="Removing-financial-functions" data-id="Removing-financial-functions" style="box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-weight: 600; line-height: 1.25; color: rgb(51, 51, 51); margin-top: 24px; margin-bottom: 16px; font-size: 1.25em; caret-color: rgb(51, 51, 51); font-style: normal; font-variant-caps: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><a class="anchor hidden-xs" href="https://hackmd.io/WuS1rCzrTYOTgzUfRJUOnw#Removing-financial-functions" title="Removing-financial-functions" smoothhashscroll="" style="box-sizing: border-box; background-color: transparent; color: rgb(51, 122, 183); text-decoration: none; float: left; padding-right: 4px; margin-left: -20px; line-height: 1;"><span class="octicon octicon-link" style="box-sizing: border-box; font-style: normal; font-variant-caps: normal; font-weight: normal; font-stretch: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-decoration: none; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; color: rgb(0, 0, 0); vertical-align: middle; visibility: hidden;"></span></a><span data-position="8801" data-size="28" style="box-sizing: border-box;">Removing financial functions</span></h3><ul class="part" data-startline="99" data-endline="101" style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; padding-left: 2em; caret-color: rgb(51, 51, 51); color: rgb(51, 51, 51); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Roboto, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: 0.3499999940395355px; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-tap-highlight-color: rgba(0, 0, 0, 0); -webkit-text-stroke-width: 0px; text-decoration: none;"><li class="" data-startline="99" data-endline="99" data-position="8833" data-size="0" style="box-sizing: border-box;"><span data-position="8833" data-size="34" style="box-sizing: border-box;">Severity: Severe (on the high end)</span></li><li class="" data-startline="100" data-endline="101" data-position="8870" data-size="0" style="box-sizing: border-box; padding-top: 0.25em;"><span data-position="8870" data-size="34" style="box-sizing: border-box;">Likelihood: Limited (maybe common)</span></li></ul><div><span data-position="8906" data-size="239" style="box-sizing: border-box;">While not used by a large user base (limited), the removal is disurptive (severe). The change ultimately required a NEP, since it is not easy to weigh the maintainence advantage of removing the functions against the impact to their users.</span></div><div><span data-position="9147" data-size="343" style="box-sizing: border-box;">The NEP included the reduction of the severity by providing a work-around: A pip installable package as a drop-in replacement (reducing the severity). For heavy users of these functions this will still be more severe than most deprecations, but it lowered the impact assessment enough to consider the benefit of removal to outweigh the impact.</span></div><div class="-x-evo-signature-wrapper"><span class="-x-evo-signature" id="none"></span></div></body></html>