Write docs for v12.2.0 minor release

[wolfgangwalther]

This is already listed in #3113 (comment), but to give this more visibility I'll create an issue about it.

Ever since merging the postgrest-docs repo into the core repo, we are supposed to merge docs together in the same PR as the corresponding feature. This didn't always happen initially, but we are getting better at it. However, we still have some unreleased feature commits on the main branch, which happened before the docs merge and thus have no corresponding docs written, yet.

This is blocking the next minor release, so needs to be taken care of.

I went through the changelog on main again, and I think the following still need to be documented:

• Dump config through Admin API #3171, Add an ability to dump config via admin API - @SkyWriter
• Dump Schema Cache through Admin API #3210, Dump schema cache through admin API - @taimoorzaeem
• Deprecated: Prefer: params=single-object is deprecated. Use a function with a single unnamed JSON parameter instead. - @steve-chavez

@steve-chavez since you merged the first two and wrote the last yourself - can you take care of the docs for those to unblock a release?

There is also #3061, which is still undocumented, but also blocking a new minor release is #3242 which will be fixed in #3358. This essentially contains the docs for #3061, too.

[laurenceisla]

• Deprecated: Prefer: params=single-object is deprecated. Use a function with a single unnamed JSON parameter instead. - @steve-chavez

I think this is already documented? I can see the deprecation notices in:

• https://postgrest.org/en/latest/references/api/functions.html#functions-with-a-single-unnamed-json-parameter, as a Warning at the end of the section.
• https://postgrest.org/en/latest/references/api/preferences.html#single-json-object-as-function-parameter, as a Warning at the start of the section

[laurenceisla]

I think this is already documented? I can see the deprecation notices in:

Ah, the link from the changelog is not working anymore though. Fixing in #3552

[steve-chavez]

I think we can do a new minor release now. @wolfgangwalther Should just doing postgrest-release be enough?

I just executed it and got:

Current version is 12.1
Updating postgrest.cabal ...
Updating CHANGELOG.md ...
Committing ...
Current version is 12.2.0
Updating postgrest.cabal ...
Committing (devel bump)...
Remote not found. Please push manually ...

I wonder why it didn't find the remote, I have:

git remote -v | grep PostgREST/postgrest
upstream        [email protected]:PostgREST/postgrest (fetch)
upstream        [email protected]:PostgREST/postgrest (push)

[laurenceisla]

Also, I think the next minor should be 12.1.0, since the latest release was 12.0.3 . Unless I'm missing something, postgrest-release should use the current version in postgrest.cabal for a minor release.

[wolfgangwalther]

Also, I think the next minor should be 12.1.0, since the latest release was 12.0.3 . Unless I'm missing something, postgrest-release should use the current version in postgrest.cabal for a minor release.

No, we agreed that uneven minor releases are the on-going development version.

So the current development version is 12.1. We are going to release 12.2 - and at the same time we switch the main branch to the new development version 12.3. That's all hardcoded in the postgrest-release tool already.

[wolfgangwalther]

I think we can do a new minor release now. @wolfgangwalther Should just doing postgrest-release be enough?

I still want to check this TODO here:

Add "pg version last supported by pgrst version X" and maybe "support for pg version Y will be removed in next version of pgrst" hints on startup as discussed in #2052 (comment).

So yeah, now it's on me.

---

I wonder why it didn't find the remote, I have:

Ah my remotes end in .git and I assume this would always be the case:

upstream	[email protected]:PostgREST/postgrest.git (fetch)
upstream	[email protected]:PostgREST/postgrest.git (push)

I will change the script accordingly.

[laurenceisla]

No, we agreed that uneven minor releases are the on-going development version.

Ah, got it, it seems that I missed that.

[wolfgangwalther]

To be precise:

• 12.1 is the development version (uneven minor, no patch)
• 12.2.0 is the proper release (even minor, including patch)

[steve-chavez]

I still want to check this TODO here:

If we do #2052, then the next version should be a major one right? Not opposed if that's the case.

[wolfgangwalther]

I still want to check this TODO here:

If we do #2052, then the next version should be a major one right? Not opposed if that's the case.

Yes - I would that right after we released the next minor.

[steve-chavez]

Yes - I would that right after we released the next minor.

Ok cool. So then I think we can release the minor now right?

[wolfgangwalther]

Ok cool. So then I think we can release the minor now right?

It depends. If you agree that I can do #2052 afterwards - fine.

In #2052 (comment) we discussed about adding the "this PG version will not be supported in the next major version"-deprecation-style check. This is the TODO I referenced here:

I still want to check this TODO here:

I was under the impression, that you agreed on doing #2052 with the condition that we add this. If so, we'd need to do that before we do the minor. If you're fine without this condition - we can go ahead with the minor release now.

[steve-chavez]

It depends. If you agree that I can do #2052 afterwards - fine.

For sure, I agree with that.

In #2052 (comment) we discussed about adding the "this PG version will not be supported in the next major version"-deprecation-style check. This is the TODO I referenced here:

Oh ok. So we need to add a deprecation plus update this section here?

[steve-chavez]

I'm kinda in need of a new version. Will make the above deprecations and try to fix the postgrest-release command.

[wolfgangwalther]

and try to fix the postgrest-release command.

I already did that a while ago.

[steve-chavez]

When trying it now I get:

$ postgrest-release 
Current version is 12.1
Updating postgrest.cabal ...
Updating CHANGELOG.md ...
Committing ...
Current version is 12.2.0
Updating postgrest.cabal ...
Committing (devel bump)...
Remote not found. Please push manually ...

Edit: Nvm, I had an outdated nix-shell. That is always confusing.

[steve-chavez]

The jump from 12.0 to 12.2 might be confusing for users. Hm, we need to document that versioning policy somewhere.

[wolfgangwalther]

I had to restart pipelines for the release twice, once for the Windows build and once for the ARM docker release. But ultimately everything should have worked now (ignore the final "failed" state for the github release, it passed before and just couldn't do it again)

[steve-chavez]

One other thing. I think we should change the CHANGELOG entries format to:

- <description, link to docs if feature> by <author> in <issue>

Instead of

- <issue>, <description> - <author>

That format is much readable for end users.

Currently I have to edit the entries manually, check https://github.com/PostgREST/postgrest/releases/tag/v12.2.0

Ideally we would have the release notes semi-automated. Not sure how to automate the subheading, maybe it should be a suggestion on a PR.

[wolfgangwalther]

One other thing. I think we should change the CHANGELOG entries format to:

- <description, link to docs if feature> by <author> in <issue>

It's hard to link to the docs at commit-time, when the new docs are not released, yet, at the right URL.

Ideally we would have the release notes semi-automated. Not sure how to automate the subheading, maybe it should be a suggestion on a PR.

I wonder whether we can use more of the github "releases" workflow for our purposes. Something like:

• have the regular tag pipeline only create the github release in "draft" mode
• create the release notes from commit messages without the changelog involved at all
• edit the release notes in the github release editor
• make the actual release by publishing the release in github

Not sure when the docker image should be pushed in this case, we could probably move it to a workflow triggered by the published release, not by the pushed tag. This would still leave a gap where the docs for the new release have already been pushed, but the release has not been made, yet. Not sure how to improve on that, yet.