mirrors/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2025-09-13 14:32:26 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

doc: explain deprecation process (#22568)

Browse source
This commit is contained in:
Pepper Gray 2024-10-18 12:11:43 +02:00 • committed by GitHub
parent ce8f62146b
commit 891a8bc362
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 17 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

17
doc/docs.md
View file

@ -5690,6 +5690,23 @@ pub mut:
Function/method deprecations:
Functions are deprecated before they are finally removed to give users time to migrate their code.
Adding a date is preferable in most cases. An immediate change, without a deprecation date, may be
used for functions that are found to be conceptually broken and obsoleted by much better
functionality. Other than that setting a date is advisable to grant users a grace period.
Deprecated functions cause warnings, which cause errors if built with `-prod`. To avoid immediate
CI breakage, it is advisable to set a future date, ahead of the date when the code is merged. This
gives people who actively developed V projects, the chance to see the deprecation notice at least
once and fix the uses. Setting a date in the next 30 days, assumes they would have compiled their
projects manually at least once, within that time. For small changes, this should be plenty time.
For complex changes, this time may need to be longer.
Different V projects and maintainers may reasonably choose different deprecation policies.
Depending on the type and impact of the change, you may want to consult with them first, before
deprecating a function.
```v
// Calling this function will result in a deprecation warning