Skip to content

Latest commit

 

History

History
44 lines (37 loc) · 4.7 KB

CONTRIBUTING.md

File metadata and controls

44 lines (37 loc) · 4.7 KB
Raw

Contributing

Welcome! Thank you for taking an interest in contributing to Vineflower.

Before making a pull request

  • The ARCHITECTURE.md file in the repository contains technical information on how Vineflower is structured. Reading that will greatly help with familiarizing yourself with the codebase and with PR development.
  • It's highly recommended to socialize your changes first through our social platforms before making a pull request!
  • Check out the issue tracker and roadmap! You can find good things to contribute there.
  • Make sure your pull request is based off of the latest development branch in the repository. The main branch is a stable snapshot, representing the latest released version of the decompiler.

Good things to contribute

  • Fixes to bugs present in the decompiler.
  • Improvements to the readability of the decompiled code.
  • New feature support for the decompiler.
  • Optimization, to make it run faster and use fewer resources.
  • Tests! Tests are always appreciated.

Where to look for things to contribute

  • The issue tracker is a great place to start. Issues tagged with "good first issue" are marked to be beginner-friendly.
  • More technical issues are usually found in the Test class where individual wrong tests are described with their errors.

Code Style and guidelines

While the code inherited from Fernflower varies with its style and syntax, it's expected that pull requests stick to our established code style.

  • We use UpperCamelCase for class names, camelCase for method, variable, local variable, and field names, and UPPER_SNAKE_CASE for static final fields. Please always qualify instance fields with a this. qualifier.
  • Please try to keep pull requests small and self-contained! It makes reviewing and maintaining the patch much easier.
  • Statements should always have braces around them, even if they are only 1 line in their length.
  • Fernflower's code is barely documented, but patches should add documentation in a high level manner so that other devs can understand what is going on within the patch, and any idiosyncrasies within.
  • When submitting new features or obscure fixes, it is also recommended to cite the relevant portion of the Java Language Specification for future reference and for getting a better understanding of the code that has to be generated by the patch.

Tests

  • Vineflower uses a large and expansive test suite to ensure that patches don't cause any regressions. Please make sure that your patches don't break any of the tests!
  • In the case that you're adding a new feature to the decompiler, it's acceptable to modify failing tests to make them succeed. Please make a note of this in the pull request.
  • When contributing, you should add new tests that cover the area of code that you are targeting. Having more tests makes the decompiler more robust, so it's always appreciated.

Resources

Fernflower is a very complex and involved bit of software, and there's a lot going on in a rather questionable structure. Naturally, understanding it all is a challenge so various resources are provided here to aid with the process.

  • Knowing how java bytecode works is essential. You can find the detailed description of all the opcodes here or a simple list of them here.
  • Graph theory comes up frequently in the statement analysis portion of Fernflower. It's useful knowing about Basic Blocks, Control Flow Graphs, and Dominators.
  • Static Single Assignment Form is also used widely to track variables and their versions within the decompilation stages.
  • The Java Language Specification, while dense, is a good source of information regarding language features.
  • The ARCHITECTURE.md file in the repository contains important information about how Fernflower is structured.
  • The social platforms contains many people who have worked with the code before, so any remaining questions are best asked there.

License

  • Vineflower is licensed under Apache Version 2.0. By submitting a patch you are agreeing to license your code under it. Please do not submit pull requests containing code you do not have the rights to!