Thanks Paulo - I'll add some notes on use of JIRA vs PR.
Somewhat related ... The actual documentation on contributing in
CONTRIBUTING.md is, well, light: two sentences total. Most of the
information is actually in patches.adoc
(https://github.com/apache/cassandra-website/blob/trunk/site-content/source/modules/ROOT/pages/development/patches.adoc).
I'm going in the direction of expanding CONTRIBUTING.md a little more to
(A) Make it more welcoming, and (B) Give new contributors a better sense
of expectations ... largely in the form of links to relevant pages on
the website.
I think, unless folks feel strongly otherwise, that I'll work guidance
on PR vs JIRA into the website docs and rely on the website docs as the
main reference.
The bulk of CONTRIBUTING.md today discusses working with submodules
(Accord specifically).
I'd like to propose moving that somewhere appropriate in
cassandra-website as well.
Any concerns about this approach overall? Thanks -- Joel.
On 8/19/2025 7:10 AM, Paulo Motta wrote:
I wanted to note that the main source of truth for design discussions
should be JIRA - GH PR interface should be mostly used for code
comments and not design discussions.
This may not be clear for new contributors which are accustomed to the
standard GH contribution workflow where design discussions take place
entirely in the PR comments section, so we may want to point that out
explicitly in the contributing guide. While GH PR comments get
mirrored in the JIRA worklog the output is harder to navigate after
the ticket is merged and the PR may not be available.
It's also helpful to add a summary to the JIRA accompanied by a short
comment of the approach taken when submitting the patch. I've seen an
increasing amount of empty JIRAs being dumped without any description
or reasoning behind decisions.
On Mon, Aug 18, 2025 at 1:52 PM Joel Shepherd <sheph...@amazon.com> wrote:
On 8/16/2025 2:39 AM, Mick wrote:
>> The important thing to know (but maybe not mention), which is
on the “how to commit” page, is that the GitHub PRs aren’t merged
directly on GitHub, they’re committed manually on the upstream git
repo branch by branch with an annotation to auto close them
downstream on GitHub
> And GitHub are not a requirement either.
>
> Contributors are free to submit patches as any of the following:
> - GH PRs
> - GH fork+branches
> - patch files attached to the jira ticket
Thanks all: appreciate folks pointing out the nuances. I'll make a
pass
to clarify the options for contributors, and take a light hand on the
committer workflow on that page.
Thanks -- Joel.
