chore: add changelogs & readme cleanups

[dtbuchholz]

Summary

• Add changelogs for each package using conventional-changelog.
• Add a root monorepo README.
• Update package READMEs with small fixes on the cloning steps (they were pointing to the old repos).

Details

To backfill the latest release changelogs, I ran the following in order:

• Root level changelog:

  npx conventional-changelog --preset angular \
  --release-count 0 --commit-path $PWD --pkg $PWD/package.json --outfile \
  $PWD/CHANGELOG.md --verbose
  

• Package level changelog:

  npx lerna exec --concurrency 1 --stream -- \
  'conventional-changelog --preset angular --release-count 0 \
  --commit-path $PWD --pkg $PWD/package.json --outfile $PWD/CHANGELOG.md --verbose'
  

This created CHANGELOG.md files at the root level as well as for each package. Fwiw, I'm not sure why the first command alone didn't generate the changelog for each package, which is why the second command was needed.

How it was tested

N/A

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[dtbuchholz]

@joewagner I want to add some sort of changelog feature to the monorepo so that I can pull these updates easily into weeknotes.

Lerna can use the conventional-changelog feature to generate changelogs, i.e., my changes did this directly with that package vs. using lerna. However, it only works with the npx lerna version --conventional-commits command, which we'd run before publishing. I'm not sure if this is feasible since we usually run npx lerna publish from-package for one package at a time. But, lerna version will update the package.json version for all packages if there a new commits in each package—it compares the commit history to the package's latest release and assumes a new semver bump is needed if there are new commits.

So, I'm not sure how feasible running lerna verson is, but maybe the commands I noted above could be part of a pre-publish npm script? Or, I can look into alternatives.

[dtbuchholz]

Here's an example of what it looks like if I run it with the what's on main:

~/tableland-js | main
> npx lerna version --conventional-commits
lerna notice cli v7.1.3
lerna info versioning independent
lerna info Assuming all packages changed
lerna info getChangelogConfig Successfully resolved preset "conventional-changelog-angular"

Changes:
 - @tableland/cli: 5.4.1 => 5.5.0
 - @tableland/local: 2.3.0 => 2.3.1
 - @tableland/node-helpers: 0.0.2 => 0.1.0
 - @tableland/sdk: 5.1.2 => 5.2.0

? Are you sure you want to create these versions? Yes
lerna info execute Skipping releases
lerna info git Pushing tags...

Note that I ran this on main because I assumed the tags wouldn't be pushed since the branch is protected. It actually did add tags to main, even though the logs said it failed—I'm not sure if that's expected or not but figured I'd share. (I deleted the tags it pushed.)

~/tableland-js | main
❯ npx lerna version --conventional-commits
lerna notice cli v7.1.3
lerna info versioning independent
lerna info Assuming all packages changed
lerna info getChangelogConfig Successfully resolved preset "conventional-changelog-angular"

Changes:
 - @tableland/cli: 5.4.1 => 5.5.0
 - @tableland/local: 2.3.0 => 2.3.1
 - @tableland/node-helpers: 0.0.2 => 0.1.0
 - @tableland/sdk: 5.1.2 => 5.2.0

? Are you sure you want to create these versions? Yes
lerna info execute Skipping releases
lerna info git Pushing tags...
lerna WARN gitPush remote: error: GH006: Protected branch update failed for refs/heads/main.        
lerna WARN gitPush remote: error: Changes must be made through a pull request.        
lerna WARN gitPush To https://github.com/tablelandnetwork/tableland-js
lerna WARN gitPush  ! [remote rejected] main -> main (protected branch hook declined)
lerna WARN gitPush  ! [remote rejected] @tableland/[email protected] -> @tableland/[email protected] (atomic transaction failed)
lerna WARN gitPush  ! [remote rejected] @tableland/[email protected] -> @tableland/[email protected] (atomic transaction failed)
lerna WARN gitPush  ! [remote rejected] @tableland/[email protected] -> @tableland/[email protected] (atomic transaction failed)
lerna WARN gitPush  ! [remote rejected] @tableland/[email protected] -> @tableland/[email protected] (atomic transaction failed)
lerna WARN gitPush error: failed to push some refs to 'https://github.com/tablelandnetwork/tableland-js'
lerna info gitPush --atomic failed, attempting non-atomic push
lerna ERR! Error: Command failed with exit code 1: git push --follow-tags --no-verify origin main
lerna ERR! remote: error: GH006: Protected branch update failed for refs/heads/main.        
lerna ERR! remote: error: Changes must be made through a pull request.        
lerna ERR! To https://github.com/tablelandnetwork/tableland-js
lerna ERR!  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR!  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR!  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR!  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR!  ! [remote rejected] main -> main (protected branch hook declined)
lerna ERR! error: failed to push some refs to 'https://github.com/tablelandnetwork/tableland-js'
lerna ERR!     at makeError (/Users/dtb/tbl/tableland-js/node_modules/execa/lib/error.js:59:11)
lerna ERR!     at handlePromise (/Users/dtb/tbl/tableland-js/node_modules/execa/index.js:114:26)
lerna ERR! lerna Command failed with exit code 1: git push --follow-tags --no-verify origin main
lerna ERR! lerna remote: error: GH006: Protected branch update failed for refs/heads/main.        
lerna ERR! lerna remote: error: Changes must be made through a pull request.        
lerna ERR! lerna To https://github.com/tablelandnetwork/tableland-js
lerna ERR! lerna  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR! lerna  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR! lerna  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR! lerna  * [new tag]         @tableland/[email protected] -> @tableland/[email protected]
lerna ERR! lerna  ! [remote rejected] main -> main (protected branch hook declined)
lerna ERR! lerna error: failed to push some refs to 'https://github.com/tablelandnetwork/tableland-js'

[joewagner]

@joewagner I want to add some sort of changelog feature to the monorepo so that I can pull these updates easily into weeknotes.

Lerna can use the conventional-changelog feature to generate changelogs, i.e., my changes did this directly with that package vs. using lerna. However, it only works with the npx lerna version --conventional-commits command, which we'd run before publishing. I'm not sure if this is feasible since we usually run npx lerna publish from-package for one package at a time. But, lerna version will update the package.json version for all packages if there a new commits in each package—it compares the commit history to the package's latest release and assumes a new semver bump is needed if there are new commits.

So, I'm not sure how feasible running lerna verson is, but maybe the commands I noted above could be part of a pre-publish npm script? Or, I can look into alternatives.

First off adding changelogs is a great idea! I wonder if there's a way to do it with github actions? I'm not familiar with conventional-changelog, maybe there's a way to ensure it's run as part of any PR where the version of a package has changed?
I'm open to idea on how we make this work, but I agree if we can avoid lerna version that sounds idea.