First time contributor experience

[Jesper Wilhelmsson]

Hi Marius,

Thank you for your experience report! This is gold to me as I'm working on improving the OpenJDK Developers' Guide. Eventually the OpenJDK Developers' Guide should be referenced from CONTRIBUTING.md but we have a few more updates to make before we want to attract too much attention to it :-)  But here it is: https://openjdk.java.net/guide/

The major update that's still pending is the move to git. The Guide still refers to mercurial. Need to fix that.

I see that you've already got the link to the bug report tool. This is mainly to be used by anyone who isn't working on OpenJDK development. Instructions on how to file a bug exists in the current Guide: https://openjdk.java.net/guide/#filing-a-bug
It's a bit hidden right now but I intend to give it a more prominent position soon.

What I really want to direct your attention to is a new section that's currently in review: https://github.com/openjdk/guide/pull/38

This intends to explain how to attack the OpenJDK as a new developer in the project. Among other things it mentions the OCA and the need for using your GitHub username.

With this new section together with what's already in the Guide many of your concerns should be addressed. From your mail I've identified the following ToDos:

* How to work with the code in an IDE
* How to create a PR (part of git rewrite)
* Where to find JTReg bundles
* How to run tests with your fork and how to navigate the test result ZIP

I'll add these to the Guide ToDo list. Please let me know if there are any questions you're still looking for answers to and I'll try to make it a priority to get those sections into the Guide asap.

Thank you!
/Jesper

> On 7 Nov 2020, at 19:54, Marius Volkhart <Marius at volkhart.com> wrote:
> 
> 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