Hey Iceberg Nation,
Last proposal from me today I promise! Another issue I've seen as I've
looked over the documentation and the release process has detracted from
both the contributor and developer experience when using Iceberg. For
example, Missing documentation for features
<https://github.com/apache/iceberg/commit/d8a07ff276dc0efbfbbe3df3579c638c863b2686>
which
causes real issues during upgrades for Iceberg users. In general, there's
not really a process to understand when changes should or shouldn't include
documentation.
As someone trying to improve the Developer Experience, I want to make using
all of the latest and awesome features you all are providing for the
community. Although I pride myself on repository detective work, I am not a
mind reader and don't have the time to play code safari to understand every
change. It is incredibly helpful to understand when a pull request is not a
user-facing change (test, documentation, internal refactoring, etc...) and
when the user or contributors should be aware of something so we can notate
that in our documentation.
Let's do better. Let's make a better developer and contributor experience!
What I don't want to do is add red tape to the development process that
inhibits our ability to deliver. That said, I want to iteratively build a
process that enables my team and others in the community interested in
lowering the on-ramp for developers for this community. Without more words,
here's what I'm proposing:
1. Roadmap tracked on GitHub Projects as opposed to website.
1. Static sites are not the easiest to keep up-to-date. It's a lot of
work to put a GitHub PR process in front of updating a word or some small
change. Rather, why don't we just use GitHub Projects and expose that on
the website?
2. We already use GitHub Projects and it’s closer to the source.
2. Some ideas gleaned from the Trino project
1. Keep a running list of merged PRs in the description of the pull
request <https://github.com/trinodb/trino/pull/19497>that updated the
release notes and add these PRs to the release milestone (ex. 1.4.0
<https://github.com/apache/iceberg/milestone/35?closed=1>)
2. Add a PR template with a release notes and docs section. Also add
checkboxes to communicate that the commit(s) are not a
user-facing change,
and no release notes/docs are needed
3. Responsibility of all of the committers/authors to add their own
release notes/docs and verify they have communicated effectively
Happy to discuss this at the sync!
