> Mihai wrote: > > I find the JIRA search difficult to use compared with github search. > As the number of issues grows, it's harder and harder to sift > through them.
Jira search isn’t great, but it isn’t terrible. The ability to cross-reference cases (with ‘related’ links) is more powerful than GitHub’s search. One pattern I use is to start in the code (it helps a lot if the test case is in the right place) and then navigate back to Jira via git blame. > Also, after the PR sometimes design questions creep on github > too as part of the review process. It's not easy to have a dialogue > that alternates between the two sites - no causality is maintained. I agree, the parallel conversations are difficult. I don’t have an easy answer. But I strongly believe that there should be a “specification” thread to the conversation and an “implementation” thread (or threads). GitHub handles the “implementation” threads well, because people just comment on the relevant line of code. (Except where the problem with the implementation is a line of code that was NOT written.) I think that reviewers should strenuously force specification topics over to Jira. > A third problem is that we have lots of contributors for whom > English is a second language (I am one of them), and sometimes > the code is easier to read than the spec... I call bullshit on that one. As a native English speaker, I can tell you that writing specifications is hard for me too. The first five years of my career I worked in UK and all of my colleagues were British. There were bad engineers too lazy to write specifications, and sometimes they worked for bad managers who let them get away with it. I know you are being kind to contributors from other cultures. But I don’t think we are doing contributors any favors by lowering our standards. (Certainly we are doing our reviewers and users no favors.) We just need to create a culture where specifications are valued. Julian > On May 20, 2025, at 11:44 AM, Mihai Budiu <mbu...@gmail.com> wrote: > > It's a good policy. > > But I find the JIRA search difficult to use compared with github search. > As the number of issues grows, it's harder and harder to sift through them. > > Also, after the PR sometimes design questions creep on github too as part of > the review process. It's not easy to have a dialogue that alternates between > the two sites - no causality is maintained. > > A third problem is that we have lots of contributors for whom English is a > second language (I am one of them), and sometimes the code is easier to read > than the spec... > > Mihai > > ________________________________ > From: Julian Hyde <jh...@apache.org> > Sent: Tuesday, May 20, 2025 11:34 AM > To: dev@calcite.apache.org <dev@calcite.apache.org> > Subject: [DISCUSS] Jira first > > Calcite has always been a "Jira first" project, where all significant > commits have a Jira case number (CALCITE-nnnn). We've not allowed > patch attachments since the very early days, so each of those commits > also has a GitHub pull request (PR). > > Given that discussion can occur on the Jira case and the PR, does it > matter where that discussion occurs? In my opinion, it makes a great > deal of difference. > > In engineering, it is essential to separate the specification of a > change (bug or feature request) from implementation. The specification > is what that change does, and the implementation is how it does it. > The specification can be understood by the end-user of the change > (often the user who writes SQL queries, but sometimes an engineer who > is using Calcite's public or private APIs), whereas an implementation > may include a brief description of an algorithm but is mainly just > code (and tests). > > Which is more important: specification or implementation? In my > opinion, specification is way more important. From a good description > of the problem, even a good one-line summary, an engineer can in most > cases create an implementation. The specification also serves > end-users (reading the release notes), it serves as documentation for > future users of the feature, and helps future maintainers figure out > how the project fits together. But if all we have is code, the only > way to understand what has been done is to read the code. This doesn't > scale. > > This has come up a couple of times recently. > > In https://issues.apache.org/jira/browse/CALCITE-7013 / > https://github.com/apache/calcite/pull/4374 there were discussions in > both the Jira and GitHub about whether this was even a desirable > change. Mihai ended up merging the PR even though I had said "This is > not a bug" in the Jira case. This is basically one committer > overriding (albeit unintentionally) another commiter's -1. > > In https://issues.apache.org/jira/browse/CALCITE-7029 / > https://github.com/apache/calcite/pull/4392 the summary is "Support > DPhyp to handle various join types", which is meaningless even to > someone like me who follows academic work on query optimization. > Jensen added a comment in the PR asking for a link to the paper where > the 'DPhyp' term was defined. (Thank you Jensen!) But really, all work > reviewing the PR should stop, until we have a good description in the > Jira case. > > I would like us to adopt two policies: > * A committer should not merge a PR until the Jira has a good summary > and description. > * Discussion in a PR about specification (what, as opposed to how) > should be moved to Jira or the dev list. > > (Personally, I will not even look at a PR until the Jira is in good > shape, but I don't expect most people would go that far.) > > Do people have comments on how we use Jira vs GitHub PRs, and how we > balance specification, implementation, and tests? > > Julian
