Skip to content

docs: turf detailed API diff reports #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 30, 2024
Merged

docs: turf detailed API diff reports #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@ A release with known breaking changes is marked with:
{issue}279[#279] ({lread})
* `rewrite-clj.paredit/barf-forward` on zipper created with `:track-position? true` now correctly barfs when current node has children
{issue}245[#245] ({lread}, thanks for the issue {person}p4ulcristian[@p4ulcristian]!)
* docs
** Turf API diff reports for now
{issue}132[#132] ({lread})

=== v1.1.47 - 2023-03-25 [[v1.1.47]]

Expand Down
1 change: 0 additions & 1 deletion bb.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@
test-doc {:task test-doc/-main :doc "test doc code blocks"}
test-libs {:task test-libs/-main :doc "(list|run|outdated) - verify that libs using rewrite-clj* work with current rewrite-clj"}
outdated {:task outdated/-main :doc "report on outdated Clojure and npm dependencies"}
doc-api-diffs {:task doc-api-diffs/-main :doc "generate diff docs for rewrite-clj* APIs"}
doc-update-readme {:task doc-update-readme/-main :doc "honour our contributors in README"}
cljdoc-preview {:task cljdoc-preview/-main :doc "preview what docs will look like on cljdoc, use --help for args"}
ci-unit-tests {:task ci-unit-tests/-main :doc "run/list continuous integration unit tests, use --help for args"}
Expand Down
8 changes: 0 additions & 8 deletions deps.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,14 +125,6 @@
;; usage -M:sci-test:gen-reflection
:gen-reflection {:main-opts ["-m" "sci-test.generate-reflection-file"]}

;;
;; Document rewrite-clj* differences (needs love!)
;;
:diff-apis {:extra-paths ["script/resources"]
:extra-deps {lread/diff-apis {:git/url "https://github.com/lread/diff-apis"
:sha "cd8096e0b5e0c0ea4850cb9eafe2d085d8912442"}}
:main-opts ["-m" "diff-apis.main" "projects"]}

;;
;; Deployment
;;
Expand Down
23 changes: 0 additions & 23 deletions doc/02-developer-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,29 +323,6 @@ You can optionally:
* `bb -lint-kondo` to run only clj-kondo linting
* `bb -lint-eastwood` to run only the eastwood linting

== API diffs
Rewrite-clj v1's primary goals include remaining compatible with rewrite-clj v0 and rewrite-cljs and avoiding breaking changes.

To generate reports on differences between rewrite-clj v0, rewrite-cljs and
rewrite-clj v1 APIs, run:

----
bb doc-api-diffs
----

WARNING: This task currently needs love, see https://github.com/clj-commons/rewrite-clj/issues/132[#132].

Run this script manually on an as-needed basis, and certainly before any official release.
Generated reports are to be checked in to version control.

Reports are generated to `doc/generated/api-diffs/` and include manually written notes from `doc/diff-notes/`.

These reports are referenced from other docs, so if you rename files, be sure to search for links.

Makes use of https://github.com/lread/diff-apis[diff-apis].
Delete `.diff-apis/.cache` if you need a clean run.


== Cljdoc Preview
Before a release, it can be comforting to preview what docs will look like on https://cljdoc.org/[cljdoc].

Expand Down
8 changes: 1 addition & 7 deletions doc/cljdoc.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,7 @@
["Developer Guide" {:file "doc/02-developer-guide.adoc"}]
["Design" {}
["Merging rewrite-clj and rewrite-cljs" {:file "doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc"}
["Namespaced Elements" {:file "doc/design/namespaced-elements.adoc"}]]
["API Differences" {}
["rwt-clj v0 vs rwt-cljs" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-cljs-lang-cljs.adoc"}]
["rwt-clj v0 vs rwt-clj v1" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-clj-v1-lang-clj.adoc"}]
["rwt-cljs vs rwt-clj v1" {:file "doc/generated/api-diffs/rewrite-cljs-lang-cljs-and-rewrite-clj-v1-lang-cljs.adoc"}]
["rwt-clj v1 clj vs cljs all" {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj.adoc"}]
["rwt-clj v1 clj vs cljs public" {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj-documented-only.adoc"}]]]
["Namespaced Elements" {:file "doc/design/namespaced-elements.adoc"}]]]
["Frequently Asked Questions" {:file "doc/03-faq.adoc"}]
["Contributing" {:file "CONTRIBUTING.md"}]
["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]
Expand Down
12 changes: 0 additions & 12 deletions doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,6 @@ We will, though, carry over rewrite-cljs's higher level positional functions.
== Changes
See link:../../CHANGELOG.adoc[change log].

=== Detailed API diffs

I've used https://github.com/lread/diff-apis[diff-apis] to compare apis.
Normally I would have excluded any apis tagged with `:no-doc` metadata, but because many folks used undocumented features in rewrite-clj v0 and rewrite-cljs, I have done a complete comparison of all publics - except where noted.
Each report contains some observations under the "Notes" header.

* link:../generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-cljs-lang-cljs.adoc[rewrite-clj v0 vs rewrite-cljs] API differences between the projects on which rewrite-clj v1 is based.
* link:../generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-clj-v1-lang-clj.adoc[rewrite-clj v0 vs rewrite-clj v1] how different is rewrite-clj v1 from rewrite-clj v0?
* link:../generated/api-diffs/rewrite-cljs-lang-cljs-and-rewrite-clj-v1-lang-cljs.adoc[rewrite-cljs vs rewrite-clj v1] how different is rewrite-clj v1 from rewrite-cljs?
* link:../generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj.adoc[rewrite-clj v1] a look at how cljs and clj sides of rewrite-clj v1 differ
* link:../generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj-documented-only.adoc[rewrite-clj v1 documented apis only] a look at how cljs and clj sides of rewrite-clj v1 differ for documented apis.

=== Feature Differences
No ability to read from files when using rewrite-clj v1 from ClojureScript.

Expand Down
Loading