Revise dev guidelines for code deprecation (#17177)

### Commit Summary
This pull request updates our coding guidelines to include a process for marking deprecated functions using metadata in ClojureScript.
This commit is contained in:
Flavio Fraschetti 2023-09-07 17:00:02 +01:00 committed by GitHub
parent a30a80f8a1
commit 3d63854b03
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 0 deletions

View File

@ -784,6 +784,28 @@ src
└── view.cljs
```
## Deprecation process
To deprecate a var, add the `:deprecated` metadata and, if necessary, suggest an
alternative.
```clojure
;; Good if there's no better alternative yet, but we want to deprecate it anyway.
(defn ^:deprecated foo
[]
(bar))
;; Good
(defn foo
{:deprecated "Use some.namespace/var-name instead."}
[]
(bar))
```
Please check the [Clojure Style](https://guide.clojure.style/#deprecated) documentation
To reduce visual clutter from deprecated methods in your text editor, consult this [example](https://rider-support.jetbrains.com/hc/en-us/community/posts/4419728641810-How-to-disable-the-the-strike-thru-for-deprecated-methods-in-Javascript-#:~:text=Try%20disabling%20%22Preferences%20%7C%20Editor%20%7C,It%20works%20for%20me). The approach can be adapted for settings in VSCode, Emacs, VIM, and others.
### Test structure
[Unit tests](#glossary) should be created alongside their respective source