Mirrors_Framework/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2026-10-06 04:59:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'GP-0_ryanmkurtz_PR-9626_jobermayr_contributing'

Browse Source
This commit is contained in:
Ryan Kurtz
2026-09-18 05:55:50 -04:00
parent 3da4e592f7 c36f60b412
commit dc9614e868
1 changed files with 59 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+59 -41
View File
@@ -1,7 +1,6 @@
# Contributor's Guide # Contributor's Guide
Ghidra is an open source project. If you are interested in making it better, there are many ways you
Ghidra is an open source project. If you are interested in making it better, can contribute. For example, you can:
there are many ways you can contribute. For example, you can:
- Submit a bug report - Submit a bug report
- Suggest a new feature - Suggest a new feature
@@ -12,84 +11,100 @@ there are many ways you can contribute. For example, you can:
- Answer questions from other users - Answer questions from other users
- Share the software with other users who are interested - Share the software with other users who are interested
- Teach others to use the software - 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 ## Bugs and Feature Requests
If you believe that you have found a bug or wish to propose a new feature, please first search the
If you believe that you have found a bug or wish to propose a new feature, existing [issues] to see if it has already been reported. If you are unable to find an existing
please first search the existing [issues] to see if it has already been issue, consider using one of the provided templates to create a new issue and provide as many
reported. If you are unable to find an existing issue, consider using one of details as you can to assist in reproducing the bug or explaining your proposed feature.
the provided templates to create a new issue and provide as many details as you
can to assist in reproducing the bug or explaining your proposed feature.
## Patch Submission Tips ## Patch Submission Tips
Patches should be submitted in the form of Pull Requests to the Ghidra [repository] on GitHub. But
first, consider the following tips to ensure a smooth process when submitting a patch:
Patches should be submitted in the form of Pull Requests to the Ghidra - Before you begin implementing, consider first opening a dialogue with the Ghidra team to ensure
[repository] on GitHub. But first, consider the following tips to ensure a that your efforts will align with the goals of the project. This may provide you with valuable
smooth process when submitting a patch: insight on what the best design and implementation strategy is, inform you about what internal
efforts may already be underway, and will significantly improve the odds that your patch gets
accepted. Unsolicited pull requests will likely receive an initial lower priority from the Ghidra
team due to our massive backlog.
- Focus your patches on bug fixes that were discovered through real-world usage and testing, and on
improvements that clearly satisfy a need in Ghidra's functionality.
- Please do not create an issue that is effectively a duplicate of your pull request. Instead,
fully describe the bug in the pull request/patch description text box.
- Ensure that the patch compiles and runs in at least our development environment, and ideally our
full build too. Even the most trivial change done in the GitHub editor has a chance to cause
problems in the full development environment for unexpected reasons.
- If using "AI" to assist in development, please apply extra scrutiny to its suggestions, in terms - If using "AI" to assist in development, please apply extra scrutiny to its suggestions, in terms
of both correctness and adherence to our [legal](#legal) requirements. of both correctness and adherence to our [legal](#legal) requirements.
- Be understanding, patient, and friendly; 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.
- Limit your patches to the smallest reasonable change to achieve your intended goal. For example, - Limit your patches to the smallest reasonable change to achieve your intended goal. For example,
do not make unnecessary indentation changes; but don't go out of your way to make the patch so do not make unnecessary indentation changes; but don't go out of your way to make the patch so
minimal that it isn't easy to read, either. Consider the reviewer's perspective. minimal that it isn't easy to read, either. Consider the reviewer's perspective.
- Isolate multiple patches from each other. If you wish to make several independent patches, do so
in separate, smaller pull requests that can be reviewed more easily.
- Unless previously authorized by the Ghidra team, repackaging, renaming, and other refactoring - 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, pollute should not be part of any pull request. These types of changes are difficult to review, pollute
the git history making it harder to do git forensics on regressions, and will likely conflict with the git history making it harder to do git forensics on regressions, and will likely conflict with
other changes that the Ghidra team is making internally. other changes that the Ghidra team is making internally.
- Avoid "find and replace" changes in your pull request. While it may be tempting to globally - Avoid "find and replace" changes in your pull request. While it may be tempting to globally
replace calls to deprecated methods or change the style of the code to fit your personal replace calls to deprecated methods or change the style of the code to fit your personal
preference, these types of seemingly trivial changes have likely not already been performed by the preference, these types of seemingly trivial changes have likely not already been performed by the
Ghidra team for good reason. Ghidra team for good reason.
- Focus your patches on bug fixes that were discovered through real-world usage and testing, and on
improvements that clearly satisfy a need in Ghidra's functionality. Before you begin - Avoid pull requests that update jars or other 3rd party libraries. It is preferred that these
implementing, consider first opening a dialogue with the Ghidra team to ensure that your efforts changes are made internally by the team. If you have a need for an updated library, please submit
will align with the goals of the project. This will significantly improve the odds that your an issue with your request instead of a pull request.
patch gets accepted.
- Unless it addresses a critical security update, avoid pull requests that update jars or other 3rd
party libraries. It is preferred that these changes are made internally by the team. If you have
a need for an updated library, please submit an issue with your request instead of a pull request.
- Before submission, please squash your commits down to a single commit that briefly describes the
changes.
- Please do not include the issue number that is being fixed in the pull request title field.
Instead, use "Fixes #xxx" somewhere in the pull request description text box.
- Isolate multiple patches from each other. If you wish to make several independent patches, do so
in separate, smaller pull requests that can be reviewed more easily.
- Avoid submitting self-generated binary files as part of your pull request. Despite your best - Avoid submitting self-generated binary files as part of your pull request. Despite your best
intentions, our policy forbids accepting them because we cannot effectively review and validate intentions, our policy forbids accepting them because we cannot effectively review and validate
their content. their content.
- Ensure that the patch compiles and runs in at least our development environment, and ideally our
full build too. Even the most trivial change done in the GitHub editor has a chance to cause
problems in the full development environment for unexpected reasons.
- Before submission, please squash your commits down to a single commit that briefly describes the
changes.
- Please do not include the issue number that is being fixed in the pull request/patch title
field. Instead, use "Fixes #xxx" somewhere in the pull request/patch description text box.
- Pull request/patch title or commit message lines must not begin with `#` since it leads to
unrecognized lines while squashing.
- Be understanding, patient, and friendly; 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.
- Be prepared to answer questions from reviewers. They may have further questions before accepting - Be prepared to answer questions from reviewers. They may have further questions before accepting
your patch, and may even propose changes. Please accept this feedback constructively, and not as a your patch, and may even propose changes. Please accept this feedback constructively, and not as a
rejection of your proposed change. rejection of your proposed change.
## Review ## Review
- We welcome code reviews from anyone. A committer is required to formally accept and merge the - We welcome code reviews from anyone. A committer is required to formally accept and merge the
changes. changes.
- Reviewers will be looking for things like threading issues, performance implications, API design, - Reviewers will be looking for things like threading issues, performance implications, API design,
duplication of existing functionality, readability and code style, avoidance of bloat duplication of existing functionality, readability and code style, avoidance of bloat
(scope-creep), etc. (scope-creep), etc.
- Reviewers will likely ask questions to better understand your change. - Reviewers will likely ask questions to better understand your change.
- Reviewers will make comments about changes to your patch: - Reviewers will make comments about changes to your patch:
- MUST means that the change is required - MUST means that the change is required
- SHOULD means that the change is suggested, further discussion on the subject may be required - SHOULD means that the change is suggested, further discussion on the subject may be required
- COULD means that the change is optional - COULD means that the change is optional
## Getting Started ## Getting Started
Once available, please see the [README][readme] and [Developer's Guide][devguide] for instructions
Once available, please see the [Developer's Guide][devguide] for instructions to set up a suitable to set up a suitable development environment.
development environment.
## Timeline and Managing Expectations ## Timeline and Managing Expectations
As we continue to engage contributors and learn best practices for running a successful open source As we continue to engage contributors and learn best practices for running a successful open source
project, our processes and guidance will likely evolve. We will try to communicate expectations as project, our processes and guidance will likely evolve. We will try to communicate expectations as
we are able to and be responsive. We hope that the community will share their suggestions for we are able to and be responsive. We hope that the community will share their suggestions for
@@ -101,6 +116,7 @@ of resources to evaluate contributions, we anticipate the following:
language specifications because these require a reasonable amount of effort to evaluate and will language specifications because these require a reasonable amount of effort to evaluate and will
help us exercise and revise our process for accepting contributions. In other words, we are going help us exercise and revise our process for accepting contributions. In other words, we are going
to start small in order to work out the kinks first. to start small in order to work out the kinks first.
- We are committed to maintaining the integrity and security of our code base. In addition to the - We are committed to maintaining the integrity and security of our code base. In addition to the
careful review the maintainers will give to code contributions to make sure they do not introduce careful review the maintainers will give to code contributions to make sure they do not introduce
new bugs or vulnerabilities, we will be trying to identify best practices to incorporate with our new bugs or vulnerabilities, we will be trying to identify best practices to incorporate with our
@@ -108,9 +124,11 @@ of resources to evaluate contributions, we anticipate the following:
are accepted. These might include things like style guides and requirements for tests and are accepted. These might include things like style guides and requirements for tests and
documentation to accompany some code contributions. As a result, it may take a long time for some documentation to accompany some code contributions. As a result, it may take a long time for some
contributions to be accepted. This does not mean we are ignoring them. 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 work flow - We are committed to integrating this GitHub project with our team's regular development work flow
so that the open source project remains dynamic and relevant. This may affect our responsiveness so that the open source project remains dynamic and relevant. This may affect our responsiveness
and ability to accept pull requests quickly. This does not mean we are ignoring them. 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 - 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 just share your code for valuable to the community. There may be times when we recommend that you just share your code for
some enhancement to Ghidra from your own repository. As we identify and recognize extensions that some enhancement to Ghidra from your own repository. As we identify and recognize extensions that
@@ -118,7 +136,6 @@ of resources to evaluate contributions, we anticipate the following:
our baseline. our baseline.
## Legal ## Legal
Consistent with Section D.6. of the GitHub Terms of Service as of 2019, and Section 5. of the Apache Consistent with Section D.6. of the GitHub Terms of Service as of 2019, and Section 5. of the Apache
License, Version 2.0, the project maintainer for this project accepts contributions using the License, Version 2.0, the project maintainer for this project accepts contributions using the
inbound=outbound model. When you submit a pull request to this repository (inbound), you are inbound=outbound model. When you submit a pull request to this repository (inbound), you are
@@ -134,5 +151,6 @@ States ("U.S.") Government and the contributor.
[issues]: https://github.com/NationalSecurityAgency/ghidra/issues [issues]: https://github.com/NationalSecurityAgency/ghidra/issues
[repository]: https://github.com/NationalSecurityAgency/ghidra/ [repository]: https://github.com/NationalSecurityAgency/ghidra/
[readme]: README.md
[devguide]: DevGuide.md [devguide]: DevGuide.md
[LICENSE]: LICENSE [LICENSE]: LICENSE