Contributing to Ghidra

​

Ways to Contribute

• Submit a bug report
• Suggest a new feature
• Provide feedback by commenting on feature requests/proposals
• Propose a patch by submitting a pull request
• Suggest or submit documentation improvements
• Review outstanding pull requests
• Answer questions from other users
• Share the software with other users who are interested
• Teach others to use the software
• Package and distribute the software in a downstream community (such as your preferred Linux distribution)

​

Bugs and Feature Requests

1. Search the existing issues to see if it has already been reported
2. If you cannot find an existing issue, use one of the provided templates to create a new issue
3. Provide as many details as possible to assist in reproducing the bug or explaining your proposed feature

​

Submitting Pull Requests

​

Submission Guidelines

• Ensure that the patch compiles and runs in at least the development environment, and ideally the full build too
• Even the most trivial change done in the GitHub editor has a chance to cause problems in the full development environment
• If using AI to assist in development, please apply extra scrutiny to its suggestions

• Limit your patches to the smallest reasonable change to achieve your intended goal
• Consider the reviewer’s perspective when structuring your changes
• Isolate multiple patches from each other - submit separate, smaller pull requests that can be reviewed more easily

• Unless previously authorized by the Ghidra team, repackaging, renaming, and other refactoring should not be part of any pull request
• These types of changes are difficult to review and pollute the git history
• Avoid “find and replace” changes in your pull request
• While it may be tempting to globally replace calls to deprecated methods or change code style, these changes have likely not been performed for good reason

• Focus patches on bug fixes discovered through real-world usage and testing
• Focus on improvements that clearly satisfy a need in Ghidra’s functionality
• Consider opening a dialogue with the Ghidra team before implementing to ensure alignment with project goals

• Unless it addresses a critical security update, avoid pull requests that update jars or other 3rd party libraries
• These changes are preferred to be made internally by the team
• If you need an updated library, please submit an issue instead of a pull request

• Avoid submitting self-generated binary files as part of your pull request
• Our policy forbids accepting them because we cannot effectively review and validate their content

​

Code Review Process

​

Review Expectations

• We welcome code reviews from anyone, though a committer is required to formally accept and merge changes
• Reviewers will be looking for:
  • Threading issues
  • Performance implications
  • API design
  • Duplication of existing functionality
  • Readability and code style
  • Avoidance of bloat (scope-creep)

​

Reviewer Feedback

• MUST means that the change is required
• SHOULD means that the change is suggested, further discussion may be required
• COULD means that the change is optional

​

Timeline and Expectations

• Developers may need time to review your submissions before they can take action or respond
• This does not mean your contribution is not valued
• If your contribution has not received a response in a reasonable time, consider commenting with a polite inquiry for an update

• Small bug fixes and code that addresses potential vulnerabilities will be prioritized
• Improvements for processor language specifications will be prioritized
• These require a reasonable amount of effort to evaluate and help exercise the contribution process

• We are committed to maintaining the integrity and security of our code base
• Careful review is given to code contributions to ensure they don’t introduce new bugs or vulnerabilities
• We are identifying best practices such as style guides and requirements for tests and documentation
• As a result, it may take a long time for some contributions to be accepted - this does not mean we are ignoring them

• We are committed to integrating this GitHub project with our team’s regular development workflow
• This may affect our responsiveness and ability to accept pull requests quickly
• This does not mean we are ignoring them

• Not all innovative ideas need to be accepted as pull requests into this GitHub project to be valuable to the community
• There may be times when we recommend that you share your code for enhancements from your own repository
• As we identify extensions of general interest to the reverse engineering community, we may seek to incorporate them into our baseline

​

Legal Requirements

• When you submit a pull request to this repository (inbound), you are agreeing to license your contribution under the same terms as specified in the LICENSE (outbound)
• This follows the inbound=outbound model

• You are offering your contribution without expectation of payment
• You expressly waive any future pay claims against the USG related to your contribution
• You acknowledge that this does not create an obligation on the part of the USG of any kind
• Your contributing to this project does not create an employer-employee relationship between the U.S. Government and the contributor

​

Getting Started

1. See the Development Setup guide for instructions
2. Review the Building Ghidra guide to ensure you can build successfully
3. Familiarize yourself with the codebase structure

​

Questions?

• Open a discussion on GitHub
• Submit a question issue using the provided template