2015-09-22 19:56:07 +08:00
|
|
|
# How to report issues
|
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
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](https://github.com/radareorg/radare2/issues))
|
|
|
|
|
|
|
|
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.
|
2015-09-22 19:56:07 +08:00
|
|
|
|
|
|
|
# How to contribute
|
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
There are a few guidelines that we ask contributors to follow to ensure that
|
|
|
|
the codebase is clean and consistent.
|
2015-09-22 19:56:07 +08:00
|
|
|
|
|
|
|
## Getting Started
|
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
* 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](https://learnxinyminutes.com/docs/git).
|
|
|
|
* 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.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
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.
|
2020-07-17 14:49:37 +08:00
|
|
|
* Check for coding style issues with:
|
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git diff master..mybranch | sys/clang-format-diff.py -p1
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
For more on the coding style, see [DEVELOPERS.md](DEVELOPERS.md).
|
|
|
|
* Open a [pull request](https://github.com/radareorg/radare2/pulls) (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/](test).
|
2015-09-22 19:56:07 +08:00
|
|
|
|
2020-07-17 14:49:37 +08:00
|
|
|
## Rebasing onto updated master
|
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
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.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
# Use SSH
|
|
|
|
git remote add radareorg git@github.com:radareorg/radare2.git
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
# Use HTTPS
|
|
|
|
git remote add radareorg https://github.com/radareorg/radare2
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
radare2 uses a `fast-forward` merging style. This means that instead of taking
|
|
|
|
the new commits you make and adding them to `master` in a single "merge
|
|
|
|
commit", the commits are directly copied and applied to `master`, "replaying"
|
|
|
|
them to bring `master` up to date with your branch.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
Default settings may create these "merge commits", which are undesirable and
|
|
|
|
make the commit history harder to read and interpret. You can set `merge` and
|
|
|
|
`pull` to fast-forward only to avoid this.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git config merge.ff only
|
|
|
|
git config pull.ff only
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
#### Step 1: Pull new commits to `master` from upstream
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git checkout master
|
|
|
|
git pull radareorg master
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
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.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
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.`.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
#### Step 2: Rebase `mybranch` onto master
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git checkout mybranch
|
|
|
|
git rebase master
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
You may optionally use the interactive mode. This allows you to reorder,
|
|
|
|
`reword`, `edit`, or `squash` your commits into fewer individual commits.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git rebase -i master
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
Again, you must resolve any conflicts that occur before you can merge.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
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.
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git checkout mybranch
|
|
|
|
git branch backup
|
|
|
|
git rebase master
|
|
|
|
```
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
#### Step 3: Publish your updated local branch
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
If you have not pushed this branch before:
|
2020-07-31 12:23:18 +08:00
|
|
|
|
2022-01-01 20:11:46 +08:00
|
|
|
```sh
|
|
|
|
git push -u origin mybranch
|
|
|
|
```
|
|
|
|
|
|
|
|
If you are updating an existing branch:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
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:
|
2020-07-31 12:23:18 +08:00
|
|
|
|
|
|
|
* Start the message capitalized (only the first character must be in uppercase)
|
2022-01-01 20:11:46 +08:00
|
|
|
* 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.:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
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 |
|
2020-07-17 14:49:37 +08:00
|
|
|
|
2015-09-22 19:56:07 +08:00
|
|
|
# Additional resources
|
|
|
|
|
2021-05-25 05:25:11 +08:00
|
|
|
* [README.md](README.md)
|
|
|
|
* [DEVELOPERS.md](DEVELOPERS.md)
|
|
|
|
* [USAGE.md](USAGE.md)
|