Stamatis, You use the word ‘patch’ to describe all code changes, but code changes are different in nature, and to be successful need to be accompanied by more than code.
A bug fix needs a good description of the bug. Not ‘I changed these lines and the problem I was having went away and so I think you should accept this patch’. The description needs to be good enough that anyone reading the release notes would understand what the problem was. And there needs to be a test case. A feature needs a description of the feature, why it is beneficial, an illustration how to use the feature, a description of the limits of the feature (edge cases) and some test cases. For both bugs and features, all that description needs to come first. For those, I just don’t agree that people can use GitHub first. GitHub tends to focus on the code, and the important stuff gets forgotten. There are other kinds of changes - improving documentation, changing the web site, adding test cases, fixing the occasional ’no brainer’ bug - but most are bug fixes or features, and I believe that “Jira first” has served us well. As a reviewer, I often won’t even look at a PR until the Jira description is in good shape. I would encourage other reviewers to do the same. Calcite is about ten years old, and is set to go on for another ten or twenty. It is in good shape because we have required analysis and documentation of code changes, not just accepted every patch that was thrown at us. Jira is a record of the design decisions that we have made. We can cross reference new bugs with the design decisions that caused them. In short, Jira is how we do software engineering. We would lose a lot if it ceases to be a central part of our process. I don’t understand what ‘milestones in GitHub’ would entail. I have no objections to that per se. Julian > On Dec 18, 2021, at 10:44 AM, Stamatis Zampetakis <zabe...@gmail.com> wrote: > > There are many good ideas in this thread and some of them we could probably > directly use without changing the current workflows a lot. > > Inspired from the discussion so far my main suggestion would be to enable > and start using the GitHub milestones keeping a one-to-one mapping with > Calcite versions. > > As other people have mentioned already, currently we allow JIRAless pull > requests and it does make sense in many cases (I will not repeat here what > others have said already). The drawback with the current process is that we > cannot associate a "fix version" if the PR does not have a JIRA and it > might be difficult to track down what changes went on which version. If we > have milestones then we can solve this inconvenience with some other added > benefits. > > Note that I am not proposing to replace JIRA. People are free to create > JIRAs and/or pull requests. The difference is that every pull request > before it gets merged should have an assigned milestone. This small > addition in our workflow will make all patches (with or without JIRA) > easier to track. > > The main goal of this change is to allow people to use JIRA, GitHub, or > both, as they prefer. This essentially means that we relax the requirement > to have a JIRA case for every patch. At a second time, we can introduce PR > templates to ensure all the necessary information is there when somebody > raises a PR. > > If people think it's worth enabling GitHub milestones I can prepare a PR > with changes in the documentation to see concretely how this will > affect our current procedures. On the other hand, if nobody sees any > advantage in using milestones then I'm fine leaving things as they are > right now. > > Best, > Stamatis > > On Mon, Dec 6, 2021 at 7:33 PM Ruben Q L <rube...@gmail.com> wrote: > >> Thanks for moving the discussion here, Vladimir. >> >> First of all, I honestly appreciate the fact that you launched this >> discussion, I think you raised some valid points; what you propose sounds >> reasonable, and it seems a valid approach too. My main argument is that I >> have no big issues with the current approach (which, of course, is not >> perfect). >> >> I guess my bottom-line is that I believe that issue tracking and version >> control (+ code review) are two different things, which serve two different >> purposes, and it is arguably a good thing to keep them separated: using >> Jira for the former and Github PRs for the latter is adequate IMO. >> >>> You did use GitHub for tracking already. >> As I see it, I have used Jira for issue tracking, and GitHub PRs for code >> review + merge. If you ask me, perhaps I am old-fashioned, but I think the >> development workflow should focus on the Jira ticket, and not on the GitHub >> PR. >> >>> Here's a good example: https://github.com/apache/calcite/pull/2329 >> I agree it is a good example. The associated Jira has several comments with >> a high-level discussion, the PR contains code-review comments for technical >> details. I am happy with this decoupling, although sometimes this is not >> always the case in all tickets; perhaps we should clarify our current >> workflow and try to enforce some rules, instead of changing it into >> something completely new. >> It is also a good example because the Jira reporter and the PR creator were >> not the same person, plus there was a span of almost two years between the >> ticket creation and the PR submission. I know this is usually uncommon, but >> it shows that there are two different roles / actions: one thing is >> describing / analyzing an issue; and a second, different thing is carrying >> out its implementation (with its corresponding code review). >> >>> GitHub allows links, and links have no properties like "caused by", >> "duplicated by". However, basic links are just enough for Calcite. >> I think it would be sad to lose this feature, but I admit it is a minor >> detail. >> >>> If you have a "customized dashboard" that is useful for many >> contributors, please show it. >> I was thinking for example at the dashboard mentioned by Stamatis, which is >> very useful (not only for the release manager, but for all contributors) >> when a release date is coming. >> >> Best regards, >> Ruben >> >> >> On Mon, Dec 6, 2021 at 12:44 PM Vladimir Sitnikov < >> sitnikov.vladi...@gmail.com> wrote: >> >>> Moving the reply to DISCUSS thread. >>> >>> Ruben>My vote might be biased because I have used Jira for many years >> (and >>> I have >>> Ruben>never used Github for issue tracking). >>> >>> It is really sad to hear. >>> You authored 87 PRs for Calcite! >>> You did use GitHub for tracking already. >>> >>> >> https://github.com/apache/calcite/pulls?q=is%3Apr+author%3Arubenada+is%3Aclosed >>> >>> Here's a good example: https://github.com/apache/calcite/pull/2329 >>> PR description says the intention of the feature. >>> There are overall and line-targeted comments. >>> Creating GitHub Issue is not that different from creating a PR. >>> >>> Ruben>I have the impression that some of the problems described >> discussion >>> are >>> Ruben>not per se Jira-related, but they appear because we misuse the >>> current >>> Ruben>tools (and it would remain more or less the same if we switched >> from >>> Jira >>> Ruben>to GitHub Issues). >>> >>> Ruben, I claim that we split information for no reason. >>> What is the real meaning behind having 50% of the review comments in >> JIRA, >>> and 50% of the comments in PR? >>> What is the real meaning behind putting "common description in JIRA, and >>> putting NO description in the PR"? >>> Does it help to have different markup languages for JIRA and GitHub? >>> >>> My main motivation is not "replace JIRA with Issues". That replacement >>> alone has few benefits. >>> The key improvement to the current process is creating PRs **with >>> description**, and keeping the relevant discussion in the PR itself. >>> I really see no point in PR comments like "let's continue in JIRA". >>> If a comment targets a specific PR, then why don't we just use PR's >>> comment fields for that? >>> >>> Ruben>high level discussion (e.g. feature design) should >>> Ruben>happen in Jira >>> >>> The vast majority of the changes are small. Adding Jira barrier for every >>> change is a productivity killer (for both contributors and for the >>> reviewers). >>> I don't mean just "switch between JIRA and PR". >>> I mean that comments are duplicated at different sites. >>> The description of the issue and the code changes are separated. >>> The notifications are duplicated (gitbox duplicates GitHub >> notifications). >>> The markup format is different. >>> The search is not coherent (there's no way to find issues and PRs at the >>> same time). >>> GitHub blame does not show the full picture (it shows PRs, however, >>> opening the JIRA is a separate step). >>> PR (and GitHub Issue) can be associated to a version, so it would be much >>> easier to relate the PR with its release version. >>> I think the list can go and go. >>> >>> Ruben>IMO every change must have a dedicated Jira ticket >>> >>> What are the benefits of "a dedicated Jira ticket"? >>> How "a dedicated Jira ticket" is different from "a dedicated PR"? >>> >>> Ruben>high level discussion (e.g. feature design) should >>> Ruben>happen in Jira, low-level details (e.g. line by line code review) >> in >>> the >>> Ruben>PR; >>> >>> Both can be in PR, so what are the benefits from splitting "low-level" vs >>> "high-level"? >>> There is a lot of cases when people discuss low-level details in JIRA. >>> >>> It would be so much better, if we aligned the review approach. >>> Jira and GitHub are just tools, and if we don't agree to review >> high-level >>> stuff first, then no tool helps. >>> That implies, GitHub is just fine for high-level reviews. >>> >>> Ruben>like customized dashboards, or linked issues ("issue A is blocked >> by >>> / >>> Ruben>caused by / duplicated by / ... issue B"). >>> >>> GitHub allows links, and links have no properties like "caused by", >>> "duplicated by". >>> However, basic links are just enough for Calcite. >>> >>> If you have a "customized dashboard" that is useful for many >> contributors, >>> please show it. >>> The ASF is a set of volunteers, so it is not right to enforce usage of >>> JIRA when only a single person needs "a customized dashboard". >>> >>> Vladimir >>> >>> >>
