Skip to content
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.

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

Getting ready to publish #99

Closed
12 tasks done
eyelidlessness opened this issue May 1, 2024 · 1 comment · Fixed by #116
Closed
12 tasks done

Getting ready to publish #99

eyelidlessness opened this issue May 1, 2024 · 1 comment · Fixed by #116
Milestone

Comments

@eyelidlessness
Copy link
Member

eyelidlessness commented May 1, 2024

While we've deferred publishing packages for our initial push to make the project public, I want to track some things we may want to discuss and a few clear tasks we should address, as we anticipate publishing in the near future.

To discuss

  • Should we adopt any specific publish-oriented tooling or processes from the Central/broader ODK team?

  • How should we handle release notes?

    I had originally set the repo up with a notion of using changesets. I've seen that base tool, along with related tools like GitHub bots which check for changesets in a PR, used effectively in other open source projects. I dropped the ball on actually using it as intended, but I'd like to discuss either reviving that effort, or other ways we might want to handle the release notes chore. I'll specifically call out that @lognaturel mentioned early on not wanting to manually maintain changelogs, a sentiment I share.

  • How should we handle versioning...

    • ... of our own packages. What mechanism do we use to update public/to-be-published packages? (Update in a PR before release, update in a PR after release with some anticipation of the next release's scope, something automated?)
    • ... of our packages' dependencies. Update before release? After? On some orthogonal schedule?
  • Do we want to publish outside of the NPM registry?

    Presumably in addition to the NPM registry, unless folks feel strongly otherwise. Examples of others we might consider:

TODO

Feel free to update this list, but I believe these are all clear tasks we should do before we publish.

  • package.json updates, project-wide:
    • Update scopes in package names to @getodk (Prepare to publish 0.1.0! #116)
    • Specify correct version for all packages we intend to publish
    • Ensure packages intended to be private are marked private, and use some form of consistent version (which may not have to ever change otherwise)
    • Add licenses field (or license if that makes more sense, depends on whether we need to use the object schema or just a string)
  • Docs (.md, JSDoc, autogenerated)
    • Update scopes where sub-packages are referenced. This is hopefully trivial to do by find-in-project, but likely won't be automated so I think it warrants tracking explicitly. Many JSDoc comments reference packages by their full scoped name. Maybe subjective whether we should update them to reflect new scopes, or unscoped as a consistent convention. (Prepare to publish 0.1.0! #116)
    • Manually validate that auto-generated docs look cromulent. I believe this is currently limited to the docs generated in xforms-engine.
  • Source code, project-wide
    • Update changed package scopes in any imports referencing them (almost certainly a find-in-project task)
  • ui-vue specific:
@github-project-automation github-project-automation bot moved this to Todo in Web Forms May 1, 2024
@lognaturel lognaturel added this to the v0.2 milestone May 9, 2024
@lognaturel
Copy link
Member

not wanting to manually maintain changelogs

I really go back and forth on this one. If we're comfortable with not having a checked-in changelog but instead only having Github releases, that's my top preference. That means we can keep release notes as living documents that evolve separately from the code. The git log is the raw source of truth about what happened.

The issue with automation around changelog building is that it requires really good discipline around Issue and PR naming. I'd like to think I'm pretty thoughtful about that kind of naming but I get it not-quite-right pretty often either because my thinking on a problem evolves as we learn more or just because I don't put enough thought into it at the time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

2 participants