Before reporting an issue on GitHub, please check that:
- You are using the most recent git version of radare2
- You are using a clean installation of radare2
- The issue has not already been reported (search here)
When the above conditions are satisfied, feel free to submit an issue. Please provide a precise description, and as many of the following as possible:
- Your operating system and architecture; e.g. "Windows 10 32-bit", "Debian 11 64-bit".
- The file in use when the issue was encountered (we may add the file or a section of it to our test suite to avoid regressions).
- A backtrace, if the issue is a segmentation fault. You can compile with ASan
on Linux using
sys/sanitize.sh
to allow easier diagnosis of such issues. - Detailed steps to reproduce the issue, including a list of commands and expected and/or actual output.
There are a few guidelines that we ask contributors to follow to ensure that the codebase is clean and consistent.
- Make sure you have a GitHub account and a basic understanding of
git
. If you don't know how to usegit
, there is a useful guide here. - Fork the repository on GitHub (there should be a "Fork" button on the top right of the repository home page).
- Create a branch on your fork based off of
master
. Please avoid working directly on themaster
branch. This will make it easier to prepare your changes for merging when it's ready.
git checkout master
git checkout -b mybranch
- Make commits of logical units. Try not to make several unrelated changes in
the same commit, but don't feel obligated to split them up too much either.
Ideally, r2 should successfully compile at each commit. This simplifies the
debugging process, as it allows easier use of tools such as
git bisect
alongside ther2r
testing suite to identify when a bug is introduced. - Check for coding style issues with:
git diff master..mybranch | sys/clang-format-diff.py -p1
For more on the coding style, see DEVELOPERS.md.
- Open a pull request (PR) on Github.
- Prefix the PR title with
WIP:
and mark it as a draft if you aren't ready to merge. - When relevant, add or modify tests in test/.
New changes are frequently pushed to the master
branch. Before your branch
can be merged, you must resolve any conflicts with new commits made to
master
.
To prepare your branch for merging onto master
, you must first rebase
it
onto the most recent commit on radareorg/master
, then, if you already pushed
to your remote, force-push
it to overwrite the previous commits after any
conflict resolution.
You may wish to change default git settings to ensure you don't need to always provide specific options. These do not need to be set again after initial configuration unless your git settings are lost, e.g. if you delete the repository folder and then clone it again.
If you cloned from your fork, you can add a new remote for upstream. The
commands here will assume that origin
is your fork and radareorg
is
upstream, but you can name them as you choose.
# Use SSH
git remote add radareorg [email protected]:radareorg/radare2.git
# Use HTTPS
git remote add radareorg https://github.com/radareorg/radare2
radare2 uses the squash
merging style to summarize changes. When your changes
are merged, the merging collaborator can customize the commit message that will
be used in master
. Typically, the pull request title is used as the commit
message. Specific or smaller changes may be included in the body.
Default settings may create "merge commits" when pulling from upstream, which
can cause issues. Set merge
and pull
to fast-forward only to avoid this.
git config merge.ff only
git config pull.ff only
git checkout master
git pull radareorg master
You may need to add the -f
flag to force the pull if it is rejected. If you
have made commits to your local master
branch (not recommended!), this may
overwrite them.
If there are new commits to master, you will see the list of changed files. If
there are no updates, you will see Already up to date.
.
git checkout mybranch
git rebase master
You may optionally use the interactive mode. This allows you to reorder,
reword
, edit
, or squash
your commits into fewer individual commits.
git rebase -i master
Again, you must resolve any conflicts that occur before you can merge.
If you are concerned about potential loss of work, you can back up your code by creating a new branch using your feature branch as a base before rebasing.
git checkout mybranch
git branch backup
git rebase master
If you have not pushed this branch before:
git push -u origin mybranch
If you are updating an existing branch:
git push -f
The -f
flag may be needed to force
the push onto the remote if you are
replacing existing commits on the remote because git commits are immutable -
this discards the old commits on your remote, and git won't take potentially
destructive actions without confirmation.
When committing changes, we ask that you follow some guidelines to keep the history readable and consistent:
- Start the message capitalized (only the first character must be in uppercase)
- Be concise. A descriptive message under 100 characters is preferred, but may not be possible in all situations. For large commits, it is acceptable to use a summary line, followed by an empty line, then an asterisk item list of changes.
- If a command is inlined, use backticks, e.g.:
git commit -m 'Modify output of `ls`'
- Add a tag if the change falls into a relevant category (see below)
- If the commit fixes an issue, you may optionally start the message with
Fix #number -
- Use present simple tense and avoid past tense. Use "add", "fix", or "change" instead of "added", "fixed", or "changed".
Tag | Relevant changes |
---|---|
##analysis |
Analysis |
##arch |
Architecture |
##asm |
Assembly (not disassembly) |
##bin |
Binary parsing |
##build |
Build system |
##config |
Configuration variables |
##cons |
Console/terminal |
##crypto |
Cryptography |
##debug |
Debugger |
##diff |
Diffing code, strings, basic blocks, etc. |
##disasm |
Disassembler |
##doc |
Documentation |
##egg |
The r_lang compiler |
##emu |
Emulation, including esil |
##graph |
Basic block graph, callgraph, etc. |
##io |
The r_io library |
##json |
JSON |
##lang |
Language bindings |
##meta |
Metadata handling, excluding printing |
##optimization |
Space/time optimizations |
##platform |
Platform-specific code |
##port |
Portability - new OS or architectures |
##print |
Printing data, structures, strings, tables, types, etc. |
##projects |
Saving and loading state |
##refactor |
Code quality improvements |
##remote |
Usage over a remote connection (TCP, HTTP, RAP, etc.), collaboration |
##search |
rafind2 , / command, etc. |
##shell |
Command-line, argument parsing, new commands, etc. |
##signatures |
Searching for or generating signatures |
##test |
Testing infrastructure, including r2r |
##tools |
r2pm , rarun2 , rax2 changes that don't fit in another category |
##util |
Core APIs |
##visual |
Visual UI, including panels |