First time contributor experience

[Marius Volkhart]

Hello,

I've been working on making my first JDK contribution, and thought I'd
provide some feedback on the process.

My motivation for contributing is that I found 2 bugs in javax.xml.

My first thought was to 1. see if there is an existing bug, and 2. if not,
file a bug. As it turns out, I can't file a bug at bugs.openjdk.java.net.
This was a pretty big demotivator, and caused me to stop JDK work for the
day. In my previous experiences with open source projects, be it Apache,
OpenJ9, or other projects on GitHub, filing a bug was very easy.

Getting the source code was really easy thanks to it being on Github now!
This was great. Unfortunately, I found myself running up a steep cliff
pretty quickly thereafter.

The CONTRIBUTING.md indirection led me to the OCA. Again, I'm used to
easier CA processes, typically something like https://cla-assistant.io/ but
it was alright. One thing that was not clear from the contributing page is
that I need to specify my GitHub username in the Username field of the OCA.
The OCA process was really fast, and Dalibor was very prompt.

Now, given that I had something I wanted to work on, and it was a minor
change most likely best discussed via code, and I already figured out
where/what the bug was, I figured I'd make a PR next. The contributing
guide doesn't know what PRs are yet, and I don't have a sponsor, so I
figured that from here on out, I was on my own.

Next I tried to get working with the code, and quickly realized that I had
absolutely no idea of how to get started with this in an IDE (Intellij in
my case). I'm used to having a Maven or Gradle project, or even something
like Bazel that lets me generate IDE project files. A guide on how to edit
the Java parts of the JDK in the popular IDEs would be immensely helpful.

Fortunately my first bug is an easy 1 line change, and doesn't need any
imports or formatting or whatever. I chose to hold off with writing a unit
test because I don't even know how to run it yet.

So now I figured I'd try the build instructions linked in the README. The
TL;DR is exactly what I wanted, and all went well until I got to running
the tier 1 tests. That step fails because something called jtreg is
missing. I tried to install via my package manager (homebrew, I'm on a Mac)
but jtreg isn't on there. I found the GitHub repo for it, but there are no
prebuilt artifacts on GitHub, and building jtreg wasn't something I wanted
to delve into. Ant & talk of JDK 7. (Several days later I found
https://ci.adoptopenjdk.net/view/Dependencies/job/jtreg/lastSuccessfulBuild/artifact
but I don't know why there are 2 versions there.)

In the course of trying to figure out what jtreg is, I learned that TestNG
is used, so I wrote my unit test in an out of band Gradle project and
copy/pasted the file into the JDK tree.

I decided to just make the change, push it, and have the GitHub Workflow
build and run the tests. The Workflow is great, and it was pretty easy to
get my fork to run the tests. How to get your fork to run the tests is
probably something that should be explained or called out in
CONTRIBUTING.md. I now wanted to see if my tests got picked up by the tool
and passed. I downloaded the test results ZIP, but am completely
overwhelmed by the contents. Is my test in testresults_part1? testsupport?
debug_testresults_common? I couldn't find it.

I gave up at this point, and just pushed the change, hoping that someone
who knows how this all works can tell me exactly what changes to make, or
will pick up the patch and do what needs to be done.

The biggest hurdles for me for working on the code are 1. Getting the code
into my IDE, and 2. Acquiring and working with jtreg. The biggest hurdle to
contributing is the inability to file bugs.

I hope this helps in improving the contributor experience.

--
Cheers,
Marius Volkhart