Achieve contribution workflow perfection (with progress) [LUCENE-10543]

[asfimport]

Inspired by Dawid's build issue which has worked out for us: #10910
He hasn't even linked 10% of the issues/subtasks involved in that work either, but we know.

I think we need a similar approach for the contribution workflow. There has been some major improvements recently, a couple that come to mind:

• Tomoko made a CONTRIBUTING.md file which github recognizes and is way better than the wiki stuff
• Some hazards/error messages/mazes in the build process and so on have gotten fixed.

But there is more to do in my opinion, here is 3 ideas:

• Creating a PR still has a massive checklist template. But now this template links to CONTRIBUTING.md, so why include the other stuff/checklist? Isn't it enough to just link to CONTRIBUTING.md and fix that as needed?
• Creating a PR still requires signing up for Apache JIRA and creating a JIRA issue. There is zero value to this additional process. We often end out with either JIRAs and/or PRs that have zero content, or maybe conflicting/outdated content. This is just an unnecessary dance, can we use github issues instead?
• Haven't dug into the github actions or configs very deeply. Maybe there's simple stuff we can do such as give useful notifications if checks fail. Try to guide the user to run ./gradlew check and fix it. It sucks to have to review, look at logs, and manually add comments to do this stuff.

So let's have an issue to improve this area.

---

Migrated from LUCENE-10543 by Robert Muir (@rmuir), updated May 04 2022
Attachments: Screen_Shot_2022-04-30_at_01.15.00.png
Sub-tasks:

• Allow Github PR link in CHANGES.html [LUCENE-10545] #11581
• Migrate to GitHub issue from Jira [LUCENE-10557] #11593
• Prepare complete migration script to GitHub issue from Jira (best effort) [LUCENE-10622] #11658

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

another idea is to use github wiki functionality vs the confluence we have today. The confluence is so out of date, and almost nobody has permissions. Somewhere buried there is instructions to ping the mailing list and ask for permissions, and rarely it happens, but come on. I think using github wiki functionality would allow it to stay up to date better?

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

another idea, add a simple "fork me on github" to the website.

Just look at our website, getting to the sources is not the easiest task. I have to evaluate a lot of open-source software myself, and always appreciate the quick link to the sources, let's not make this difficult.

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

Believe it or not, there's actually no "link" to the source code anywhere, only commandline instructions to run git clone https://github.com/apache/lucene.git. You can contribute changes to stuff like documentation straight from the github UI. no need to do stuff from any commandline. Linking to the sources appropriately (especially given that the repo has moved from lucene-solr to lucene), seems like priority number one.

[asfimport]

Dawid Weiss (@dweiss) (migrated from JIRA)

("with progress"... yeah, that's why #10910 is still open :) )

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

It was entirely too difficult to find the issue! I knew it had "perfection" in the name too!!!!

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

Creating a PR still requires signing up for Apache JIRA and creating a JIRA issue. There is zero value to this additional process. We often end out with either JIRAs and/or PRs that have zero content, or maybe conflicting/outdated content. This is just an unnecessary dance, can we use github issues instead?

Yes I think it's an obstacle to contributing (in this GitHub era) when developers already have a working patch... As far as I know, the only technical reason to ask contributors to open a JIRA issue is that our CHANGES (or changes2html.pl) requires it. (I have no opinion about replacing JIRA with GitHub issue.)

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

I just found that it looks like changes2html.pl supports github PRs, the url is obsoleted though.

lucene/gradle/documentation/changes-to-html/changes2html.pl

Line 28 in a8d86ea

my $github_pull_request_prefix = 'https://github.com/apache/lucene-solr/pull/';

[asfimport]

Michael McCandless (@mikemccand) (migrated from JIRA)

+1 to work out a migration plan to switch to GitHub issues.  Can we preserve our whole history here?

The most compelling reason to me is that our Jira instance still does not (cannot?) support Markdown.  Maybe all these comments where we all optimistically tried to use Markdown will then render correctly on migration to GitHub issues!!

I even see attempted Markdown in our CHANGES.txt, but does our changes2html.pl support rendering/translating MD to HTML?

Hmm then I will have to figure out how to migrate https://jirasearch.mikemccandless.com near-real-time indexing onto GitHub issues too!

[asfimport]

Michael McCandless (@mikemccand) (migrated from JIRA)

Also, I love this new "Achieve XYZ perfection (with progress)" template ;)

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

I opened #11581 and a PR for it. Can you please take a look?
It does not aim to replace Jira with GitHub, but relaxes the requirement for Jira account/issue for contributors who are ready to start the conversation with a working PR. This would make some progress I think.

For the future, we could consider replacing Jira with Github issue - I'm not against it and it may be technically possible, I think we'd need some additional discussion (also with ASF, maybe?) for the big transition.
I have no personal opinion about the migration to GitHub - Jira works well for me so far and I'm already accustomed to concurrent use of Jira and GitHub.

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

IMO it just creates friction. having to sign-up for an account on anything is a big hurdle IMO. Signing up for JIRA is something i haven't done in forever, so I've got a screenshot of what it looks like. You have to solve CAPTCHA, etc:

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

I forgot the sign-up procedure of Jira, but generally agree with it's cumbersome and I don't like CAPTCHA too :)

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

I found GitHub issue is enabled on Apache Airflow and BookKeeper (and a few more) repositories, and they already use it:

https://github.com/apache/airflow/issues

https://github.com/apache/bookkeeper/issues

So I see no (technical) reason why we can't move to GitHub issues from Jira, although I'm not sure how to smoothly migrate/operate it. Maybe, we should look for an INFRA Jira...

[asfimport]

Tomoko Uchida (@mocobeta) (migrated from JIRA)

Ok, I don't know how difficult it is though, opened an issue: #11593.
Please join it if you are interested (+1 or -1, either feedback is welcome :)