Recommendations for new contributors

[danthe1st]

Contributing to big projects like the Eclipse IDE can be overwhelming - especially when these projects are distributed across many repositories and organizations with each repository containing a lot of directories with non-obvious purposes (at least to someone who never contributed to the Eclipse IDE). However, this shouldn't be demotivating.
Before I start, I quickly want to mention that nothing here is a secret. These are just my experiences contributing and mistakes I made along the way (even if I don't know how to do some things, at least I know some things not to do).

Why contribute?

Contributing to a project like the Eclipse IDE (typically) requires putting in a notable amount of effort to find what you want to change, understanding the existing code, making your change, debugging it and finally submitting a PR and addressing the comments during the review. However, contributing can also help you a lot. By contributing improvements to tools like the Eclipse IDE, you are improving the tools that you are using and not just improving your life working with these tools but also making it better for anyone else who might be facing similar issues. Furthermore, you will learn a lot by contributing to the Eclipse IDE. You will gain experience navigating and understanding big codebases, get your code reviewed by experts in these topics and improve your problem-solving and programming skills overall. While you can also improve without it, contributing to Open Source projects will lead to you learning faster than you would otherwise. In addition to that, having contributed to Open Source projects can even help with getting a job! Interviewers may look at GitHub and other accounts and seeing that you have provided contributions to well-known Open Source projects can certainly put you at an advantage compared to other candidates with similar levels of experience. You can even name some projects you contributed/link to some of your contributions to on your CV (or possibly platforms like LinkedIn if you use that) but don't try to make employers think these are actual job positions (unless they are - they will check your background).

In my opinion, every (experienced) developer should have contributed to Open Source projects they (or their team) are using.

General recommendations

Start with small things. Maybe there's a small bug somewhere that annoys you? Maybe Eclipse is stuck doing some operations (create a thread dump, see where it's stuck and fix it)? Maybe you would benefit from some quickfix being available somewhere? These are good places to start for your (first) contribution. Starting with smaller things/bugfixes will make it easier for you and you can still move on to implementing more complicated functionality after a few small/easy contributions. I don't recommend trying to make changes that span over many different components if you aren't experienced with the Eclipse codebase(s). Don't think you can change something about how all editors work (or similar) and expect it to not cause any issues.

If (easily) possible, I'd also recommend starting with Eclipse projects that are comparatively small, just because it won't be as overwhelming and might be easier to get started with compared to projects like Eclipse Platform or JDT. Is there something you'd like to improve about the Maven or Gradle support? Maybe the git tooling or the HTML/JSON/YAML/XML, etc. support? Are you using language servers in Eclipse? Maybe even some projects that aren't under the Eclipse Foundation umbrella like Spring Tools? There are a lot of projects you can contribute to and I'm sure most of them (at least those that are maintained by the Eclipse Foundation, I can't make promises for anything else) will welcome you with open hands (assuming you are providing a high-quality change and are overall respectful etc).

That being said, having some experience with Eclipse plug-in development (or having written your own Eclipse plugins) certainly makes some things easier (because the same tooling and APIs are also used within the IDE) but this is by no means necessary. You can pick up the necessary things along the way (and contributing to the aforementioned smaller projects can help with that).

Starting with your contribution

Before you are able to work on whatever you'd like to change, you need to find the project to contribute to. A basic overview of the fundamental components of the IDE can be found here. The "Report a problem" button in the "Help" menu also redirects you to a page that shows you a list of projects that you got when you installed Eclipse. This page also has short descriptions for many projects. If you already made a thread dump or stack trace of the problem you are trying to solve, that might also give you an indication of which project may be involved.

When it comes to setting your development environment for working on the Eclipse IDE, I highly recommend following the instructions. Don't think you can just import these projects as Maven projects and expect everything to work but actually do what is mentioned in the README.md or CONTRIBUTING.md files. Many projects have a "Create Development Environment" button that you can click or drag into the Eclipse installer to set up Eclipse with the project. If such a button is not available, there are typically other instructions in the README or CONTRIBUTING files. Follow these instructions instead of making your own setup that might just cause issues for you along the way. Also, if you really want to setup these projects your own way, at least create a dedicated workspace for it.
These buttons looks similar to the following:

One thing to note is that you will need to use Maven 3 (I'd suggest using the latest version of Maven 3 from https://maven.apache.org/download.cgi) if you want to build Eclipse IDE projects from the command-line (at least at the time of writing this). If you attempt to use Maven 4, you will get a confusing error.

Making your change

One thing you should be careful when working on the Eclipse IDE is to not break API compatibility. If there is a method that is part of the API (typically a public method of a public class in a package that doesn't contain internal in its name), you shouldn't remove it or change its signature. For interfaces that are part of the API, you should also not add additional methods and so on. Basically, don't break any code that might be using non-internal/public APIs.

To test your changes, you can use "Eclipse application" run configurations. You can create a new run configuration of that type like any other run configuration and optionally configure the Plug-ins/features that will be included in the Plug-ins tab. Running that will basically start Eclipse from Eclipse and you can debug it like any other Java application.

When it comes to testing your code, take a look at existing tests for the functionality you are modifying and add tests as needed (similar to the existing ones). To run the tests, make sure you select to run them as "JUnit Plug-In Test"s and not "JUnit Test"s as the latter will not work properly.

If you are creating a new test class, you might need to add it to a test suite class to ensure they are actually executed in builds. Find the appropriate class (annotated with @Suite) and add your test class to that suite in the @SelectClasses annotation.

Submitting your changes

Once you have made your changes and finished testing them, you can push them to your fork and create a pull request. When doing so, please make sure that your PR consists of a single commit containing your change (another commit for version bumps is ok if necessary). If you want to change what you did, you can "amend" the commit (changing the existing commit). When you want to integrate the latest changes from the master branch (especially if you have worked on your changes for multiple days), please rebase your branch on top of the master branch and don't create merge commits (don't merge other changes into yours).

Don't expect to be done when you are submitting your pull request. Reviewers will likely request changes you'll need to address before your PR gets integrated. When being asked to make changes, amend your commit, force push to your branch, mark the reviewer comments as resolved and ping them saying you made these changes.

Keep your PRs as small as possible. Reviewing big pull requests takes a lot of effort and is a waste of time on the reviewer's side. Don't implement multiple things in a single PR. Instead, split your changes into multiple pull requests that can be reviewed on their own if possible. The reviewers will be thankful for that.

After submitting your PR, you might see the builds fail for some reason. If you inspect the logs and see test failures which are likely caused by you (if the same test failures can be found in master or other PRs, they are probably not caused by you - the reviewers can probably tell you whether these test failures are known issues), you can probably ignore them. If the build fails due to missing version bumps, you probably don't have to worry too much about it. Most projects use GitHub Actions to automatically add a commit with version bumps if necessary but if it's your first contribution to that project, these builds need to be approved by a committer. Ideally, these version bumps should be their own commit and not be included in the same commit you are making your changes with. If you want to fix these version bumps by yourself, you will need to increase the version of the relevant (sub)projects in the pom.xml and META-INF/MANIFEST.MF files (these versions must match). When doing so, make sure to increment the minor version by 100 (e.g. if the version was 2.3.400 before, change it to 2.3.500).

Keep in mind that the committers/maintainers are people with limited time. If they overlook your PR/don't notice it for a while, check who has been working on similar functionality in the project recently (e.g. check for people who recently changed something in the same package) and ping them in your PR asking for a review. If someone already reviewed it and you need a re-review, you can also ping them.

All contributors to Eclipse Foundation projects need to sign the Eclipse Contributor Agreement which grants certain rights on the code you contribute to the Eclipse Foundation. You will need to sign that if you want to contribute code to the Eclipse IDE. Similarly, all source files need to have a copyright header at the top. That is a comment with a copyright disclaimer, year the file was created and modified last and a list of people or companies who provided significant contributions. When your pull requests adds new files, make sure to add the copyright header (take a look at similar source files to see what it is supposed to look like).

Getting help

Finally, if you might need help with contributing to the Eclipse IDE, don't hesitate to ask. For example, you can create a discussion here (or possibly in the repository of the project you want to contribute to if you have a specific question about that project) which is probably the easiest option or you can ask in the Eclipse-IDE Newcomers chatroom. For other issues related to contributing to the Eclipse IDE (especially your first contributions), you can probably also ask @HannesWell and they should hopefully be able to redirect you to the right people. If you want to, you can also contact me directly in some way and I might be able to help if I have time but keep in mind that I'm not that experienced when it comes to working on the Eclipse IDE.