Skip to content

Latest commit

 

History

History
225 lines (177 loc) · 8.03 KB

CONTRIBUTING.md

File metadata and controls

225 lines (177 loc) · 8.03 KB
Raw

How to report issues

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.

How to contribute

There are a few guidelines that we ask contributors to follow to ensure that the codebase is clean and consistent.

Getting Started

  • Make sure you have a GitHub account and a basic understanding of git. If you don't know how to use git, 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 the master 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 the r2r 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/.

Rebasing onto updated master

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.

Step 0: Configuring git

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 git@github.com: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

Step 1: Pull new commits to master from upstream

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..

Step 2: Rebase mybranch onto master

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

Step 3: Publish your updated local branch

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.

Commit message guidelines

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".

Commit message tag list

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

Additional resources