Hi Joel, You are asking all the right questions here for updating this process and from a quick scan of the links on this thread, it's clear CONTRIBUTING.md needs some attention.
I know from our conversations that this is not your first time at the rodeo, so feel free to bring this doc (and related if you want) up to par. Either way, thanks for calling this out and the effort so far! Cheers, -Nate On Wed, Aug 20, 2025 at 9:25 AM Joel Shepherd <sheph...@amazon.com> wrote: > 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. >> >>
