snmvaughan opened a new pull request, #7668:
URL: https://github.com/apache/datafusion-comet/pull/7668

   ## Which issue does this PR close?
   
   There is no issue for this. It comes out of reviewing #7513, the 
`branch-1.2` backport of #6928. It adds compatibility notes for `percentile` 
that the frozen 1.2 compatibility pages did not yet show when I reviewed it.
   
   ## Rationale for this change
   
   A release branch commits the generated docs that `main` fills in at publish 
time, so the archived docs for a release show real content. The release process 
says the script freezes three things: the config reference, the Implementation 
column of the Spark Expression Support page, and the per-Spark-version 
compatibility pages.
   
   The backporting guide's list of differences that are easy to miss names only 
`configs.md`. The compatibility pages are frozen the same way. They render what 
an expression serde reports through `getCompatibleNotes`, 
`getIncompatibleReasons` and `getUnsupportedReasons`, and they hold the cast 
support tables. A backport that changes any of these leaves the release docs 
stale unless it updates the pages too. #7489 did, for its changed reasons. 
Nothing in the guide says to, so it is easy to miss.
   
   ## What changes are included in this PR?
   
   One bullet in `docs/source/contributor-guide/backporting.md`, next to the 
`configs.md` one. It says the per-version compatibility pages are frozen the 
same way, names what changes their content, and tells the author to update the 
matching section in each page the backport affects. It also says that rerunning 
`./dev/generate-release-docs.sh` and reading `git diff` shows the exact text, 
at the cost of one Maven build per Spark version, and that the script rewrites 
every frozen page, so the author should keep only the hunks the backport 
changes.
   
   No backport of this change is needed, because only 
`docs/source/user-guide/latest/` is published from a release branch.
   
   The draft #7112 edits the bullets on either side of this one and renames 
`user-guide/latest` to `user-guide/dev` on `main`. Whichever of the two lands 
second needs a small rebase. The path in this bullet is right for `main` and 
`branch-1.2` today, and would need the same rename if #7112 lands first.
   
   ## How are these changes tested?
   
   Documentation only.
   
   - `prettier --check` with the latest prettier (3.10.1), which is what CI 
installs, passes on the changed file.
   - I checked the claims against `dev/generate-release-docs.sh`, the "Generate 
Release Documentation" section of `release_process.md`, and `branch-1.2`. That 
branch commits five `spark-<version>` directories, their `cast.md` pages hold 
the generated cast tables, and #7489 updated four of the five in its backport.
   - I read `dev/generate-release-docs.sh` but did not run it. It runs one 
Maven build per profile and, on every run, rewrites `configs.md` and 
`expressions.md` and formats the pages under `latest/` with the latest 
prettier. That is why the bullet says to keep only the hunks the backport 
changes. The sentence that recommends rerunning it is still worth a check from 
someone who has run the script on an existing release branch.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to