Improve contribution guidelines (#2293)
* Improve contribution guidelines
4
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -1,8 +1,8 @@
|
||||
<!-- Filling this template is mandatory -->
|
||||
|
||||
**Your checklist for this pull request**
|
||||
- [ ] I've read the [guidelines for contributing](https://cutter.re/docs/developers-docs/first-time.html) to this repository
|
||||
- [ ] I made sure to follow the project's [coding style](https://cutter.re/docs/developers-docs.html)
|
||||
- [ ] I've read the [guidelines for contributing](https://cutter.re/docs/contributing/code/getting-started.html) to this repository
|
||||
- [ ] I made sure to follow the project's [coding style](https://cutter.re/docs/contributing/code/development-guidelines.html)
|
||||
- [ ] I've updated the [documentation](https://cutter.re/docs/user-docs.html) with the relevant information (if needed)
|
||||
|
||||
|
||||
|
@ -12,7 +12,7 @@ You can create an issue by clicking on [this link](https://github.com/radareorg/
|
||||
|
||||
Note that cutter is still under development and many parts of the code are to be improved.
|
||||
The best way is to check the opened issues [here](https://github.com/radareorg/cutter/issues) or discuss with radareorg team.
|
||||
Please follow our contribution guidelines: https://cutter.re/docs/developers-docs.html
|
||||
Please follow our contribution guidelines: https://cutter.re/docs/contributing.html
|
||||
|
||||
## Contributing to the documentation
|
||||
|
||||
|
1
docs/.gitignore
vendored
@ -1,3 +1,4 @@
|
||||
/doxygen-out
|
||||
/build
|
||||
/source/api
|
||||
/source/_build
|
||||
|
@ -1,9 +1,16 @@
|
||||
{% extends 'basic/layout.html' %}
|
||||
{% block extrahead %}
|
||||
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous">
|
||||
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous">
|
||||
<script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
|
||||
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
|
||||
{% endblock %}
|
||||
|
||||
{# https://www.sphinx-doc.org/en/master/templating.html #}
|
||||
|
||||
{% block relbar1 %}{% if pagename != 'index' %}{{ relbar() }}{% endif %}{% endblock %}
|
||||
|
||||
{% block relbar2 %}
|
||||
{% endblock %}
|
||||
|
||||
|
106
docs/cutter_theme/static/admonitions.css
Normal file
@ -0,0 +1,106 @@
|
||||
/* Admonition styles */
|
||||
div.admonition {
|
||||
padding: 8px 35px 8px 0px;
|
||||
margin-bottom: 20px;
|
||||
text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
|
||||
border: 1px solid ;
|
||||
color: #3a87ad;
|
||||
background-color: #d9edf7;
|
||||
border-color: #bce8f1;
|
||||
|
||||
-webkit-border-radius: 4px;
|
||||
-moz-border-radius: 4px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
div.admonition p {
|
||||
margin: 0.5em 1em 0.5em 1em;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
div.admonition pre {
|
||||
margin: 0.4em 1em 0.4em 1em;
|
||||
}
|
||||
|
||||
div.admonition p.admonition-title {
|
||||
margin: 0;
|
||||
padding: 0.1em 0 0.1em 0.5em;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
div.admonition ul, div.admonition ol {
|
||||
margin: 0.1em 0.5em 0.5em 3em;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
/* -- danger, error -- */
|
||||
div.danger,
|
||||
div.error {
|
||||
color: #b94a48;
|
||||
background-color: #f2dede;
|
||||
border-color: #eed3d7;
|
||||
}
|
||||
|
||||
|
||||
/* -- warning, caution, attention -- */
|
||||
div.warning,
|
||||
div.caution,
|
||||
div.attention {
|
||||
color: #c09853;
|
||||
background-color: #fcf8e3;
|
||||
border: 1px solid #fbeed5;
|
||||
}
|
||||
|
||||
/* -- note, important -- */
|
||||
div.note,
|
||||
div.important {
|
||||
color: #468847;
|
||||
background-color: #dff0d8;
|
||||
border-color: #d6e9c6;
|
||||
}
|
||||
|
||||
/* -- hint, tip -- */
|
||||
div.hint,
|
||||
div.tip {
|
||||
color: #3a87ad;
|
||||
background-color: #d9edf7;
|
||||
border-color: #bce8f1;
|
||||
}
|
||||
|
||||
div.danger p.admonition-title:before,
|
||||
div.error p.admonition-title:before,
|
||||
div.warning p.admonition-title:before,
|
||||
div.caution p.admonition-title:before,
|
||||
div.attention p.admonition-title:before,
|
||||
div.important p.admonition-title:before,
|
||||
div.note p.admonition-title:before,
|
||||
div.hint p.admonition-title:before,
|
||||
div.tip p.admonition-title:before
|
||||
{
|
||||
display: inline-block;
|
||||
font-family: FontAwesome;
|
||||
font-style: normal;
|
||||
font-weight: normal;
|
||||
line-height: 1;
|
||||
-webkit-font-smoothing: antialiased;
|
||||
-moz-osx-font-smoothing: grayscale;
|
||||
}
|
||||
|
||||
div.danger p.admonition-title:before,
|
||||
div.error p.admonition-title:before {
|
||||
content: "\f06a\00a0";
|
||||
}
|
||||
div.warning p.admonition-title:before,
|
||||
div.caution p.admonition-title:before,
|
||||
div.attention p.admonition-title:before {
|
||||
content: "\f071\00a0";
|
||||
}
|
||||
div.important p.admonition-title:before,
|
||||
div.note p.admonition-title:before {
|
||||
content: "\f05a\00a0";
|
||||
}
|
||||
div.hint p.admonition-title:before,
|
||||
div.tip p.admonition-title:before {
|
||||
content: "\f0eb\00a0";
|
||||
}
|
||||
|
@ -68,10 +68,6 @@ div.footer a {
|
||||
color: #888;
|
||||
}
|
||||
|
||||
div.related {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.sphinxsidebar a {
|
||||
color: #444;
|
||||
text-decoration: none;
|
||||
@ -359,7 +355,7 @@ code.descname {
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
@media screen and (max-width: 875px) {
|
||||
@media screen and (max-width: 1050px) {
|
||||
body {
|
||||
margin: 0;
|
||||
padding: 20px 30px;
|
||||
@ -493,4 +489,4 @@ kbd kbd:hover {
|
||||
kbd:active kbd {
|
||||
box-shadow: 0px 0px 0px black;
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
|
5
docs/cutter_theme/static/cutter.js
Normal file
@ -0,0 +1,5 @@
|
||||
|
||||
// Make sure that external links are opened in new tabs
|
||||
$(document).ready(function() {
|
||||
$("a[href^='http']").attr('target','_blank');
|
||||
});
|
@ -104,6 +104,15 @@ html_logo = '../../src/img/cutter.ico'
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
# html_static_path = ['static']
|
||||
|
||||
html_js_files = [
|
||||
'cutter.js',
|
||||
]
|
||||
|
||||
html_css_files = [
|
||||
'cutter.css',
|
||||
'admonitions.css'
|
||||
]
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
|
29
docs/source/contributing.rst
Normal file
@ -0,0 +1,29 @@
|
||||
Contributing to Cutter
|
||||
=======================
|
||||
|
||||
So you like Cutter and want to get involved? Great! This part of the documentation will help and guide you through everything you need to know when contributing to Cutter. Welcome, we're delighted to see you!
|
||||
|
||||
.. tip::
|
||||
**Need help?** Our community strives to be friendly, open, and accessible for new contributors. If you have any difficulties getting involved or finding answers to you questions, please `come and ask your questions on our Telegram or IRC groups <https://cutter.re/#community>`_.
|
||||
|
||||
We know that set up to work on Cutter and finding issues that are a good fit for your skills can be a challenge. We're always looking for ways to improve this process: making Cutter more open, accessible, and easier to participate with. If you're having any trouble following this documentation or hit a barrier you can't get around, please contact us.
|
||||
|
||||
.. rubric:: How do you want to help?
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<a class="btn btn-outline-primary btn-lg m-2" role="button" href="contributing/code/getting-started.html">Code</a>
|
||||
<a class="btn btn-outline-warning btn-lg m-2" role="button" href="contributing/docs/getting-started.html">Documentation</a>
|
||||
<a class="btn btn-outline-success btn-lg m-2" role="button" href="contributing/plugins/getting-started.html">Plugins</a>
|
||||
<a class="btn btn-outline-info btn-lg m-2" role="button" href="contributing/translations/getting-started.html">Translations</a>
|
||||
|
||||
---------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:titlesonly:
|
||||
|
||||
contributing/code
|
||||
Contributing Documentation <contributing/docs/getting-started>
|
||||
contributing/translations/getting-started
|
||||
contributing/plugins/getting-started
|
14
docs/source/contributing/code.rst
Normal file
@ -0,0 +1,14 @@
|
||||
Developer Documentation
|
||||
=======================
|
||||
|
||||
.. note::
|
||||
New to Cutter development? Check out our :doc:`tutorial for new developers <code/getting-started>`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
Getting Started <code/getting-started>
|
||||
code/development-guidelines
|
||||
code/ide-setup
|
||||
code/*
|
@ -24,9 +24,9 @@ memory state as it was at the moment of the crash.
|
||||
|
||||
Then the crash dialog is shown:
|
||||
|
||||
.. image :: images/crash-dialog.png
|
||||
.. image :: /images/crash-dialog.png
|
||||
|
||||
If the user chooses to create a crash dump, the prepared dump is moved to the directory specified by user.
|
||||
And then the success dialog is shown:
|
||||
|
||||
.. image :: images/success-dump-dialog.png
|
||||
.. image :: /images/success-dump-dialog.png
|
@ -1,24 +1,19 @@
|
||||
Developer documentation
|
||||
=======================
|
||||
|
||||
This page shows some hints about the coding conventions.
|
||||
Cutter Development Guidelines
|
||||
===============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
developers-docs/*
|
||||
crash-handling-system
|
||||
.. note::
|
||||
New to Cutter development? Check out our :doc:`tutorial for new developers <getting-started>`.
|
||||
|
||||
|
||||
Cutter coding advices
|
||||
---------------------
|
||||
Common Usage
|
||||
--------------
|
||||
|
||||
CutterCore class
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the main class where every link with r2 is made. It is *unique*
|
||||
accross the whole process. To access it, simply call ``Core()``.
|
||||
across the whole process. To access it, simply call ``Core()``.
|
||||
|
||||
Example:
|
||||
|
||||
@ -35,7 +30,8 @@ There are multiple ways to call a radare2 command:
|
||||
This is the command we used to fetch structured data from radare2.
|
||||
|
||||
- ``CutterCore::cmdRaw(<command>)`` - Executes a single radare2 command
|
||||
without going through radare2 shell functionality like output redirects, grep, and multiple command parsing.
|
||||
without going through radare2 shell functionality like output redirects, grep, and multiple command parsing.
|
||||
|
||||
The command then returns its output. This should be used when a command doesn't have output or the output should be handled as-is. If possible, using the json variation with ``cmdj`` is always preferred.
|
||||
|
||||
- ``CutterCore::cmdRawAt(<command>, <address>)`` - Executes a single radare2 command in a given address and returns the output. This helps avoiding weird strings concatenation like ``cmd("ph " + hash + " @ " + QString::num(address))``.
|
||||
@ -80,7 +76,7 @@ so your widget refreshes its output when radare2 seek is modified
|
||||
(switching to another function, etc.).
|
||||
|
||||
Coding style
|
||||
------------
|
||||
-------------
|
||||
|
||||
In general, we follow `the official Qt guidelines <https://wiki.qt.io/Qt_Coding_Style>`__ to
|
||||
format the code. If in doubt, you can use `AStyle
|
96
docs/source/contributing/code/getting-started.rst
Normal file
@ -0,0 +1,96 @@
|
||||
Contributing code to Cutter
|
||||
============================
|
||||
|
||||
Thank you so much for your interest in contributing to Cutter! Contributors like you are a treasured resource for Cutter and their contributions have made the project what it is. And so, we appreciate everyone who gives the community the gift of their time <3.
|
||||
|
||||
The following section in our documentation is *not* intended to be comprehensive but rather a quick guide to walk you through the basic flow of contributing to Cutter. For more thorough documentation, follow the links on this page and read our Development Guidelines.
|
||||
|
||||
Clone and compile Cutter
|
||||
-------------------------
|
||||
The first step before starting to add code to Cutter is to build it on your environment. Whether it is Linux, Windows, or macOS, we have you covered and detailed the instructions to compile Cutter on our :doc:`/building`. Once you are done and Cutter was built successfully, test that it works correctly and continue to the next steps.
|
||||
|
||||
.. tip::
|
||||
If you are facing issues with building Cutter on your environment, make sure you didn't miss anything in the documentation. Specifically, check the :ref:`Building:Troubleshooting` section.
|
||||
|
||||
.. tip::
|
||||
If you need help configuring your development environment, make sure to read our :doc:`instructions, recommendations and tips <ide-setup>` for setting up a Cutter development environment for popular IDEs.
|
||||
|
||||
|
||||
|
||||
Find something to work on
|
||||
--------------------------
|
||||
Some will reach this page with a clear idea of what issue they want to fix or what feature they wish to implement. But some would simply want to help Cutter getting better while doing open-source, without having a specific thing in mind. If you already have something in mind - great! Move forward to the next section. If you don't have anything specific, stick with us a little bit more.
|
||||
|
||||
The issues and the feature-requests of Cutter are listed and tracked on our `Github Issues <https://github.com/radareorg/cutter/issues>`_ page. Don't get scared by the number of issues open, we will learn how to filter them to find those which fit you best.
|
||||
|
||||
.. tip::
|
||||
**Fix your pet peeve!** Anything specific that annoys you about Cutter? Fantastic! This can be a great place to start.
|
||||
|
||||
|
||||
Organizing issues
|
||||
*******************
|
||||
In order to organize the hundreds of Issues opened on Cutter, we use several features of Github for project management. Get yourself familiar with the following features, it will help you filter the issues.
|
||||
|
||||
Labels
|
||||
^^^^^^^^
|
||||
Tagging issues and pull requests with labels allows us to quickly search for them later. We use labels to describe the type of the issue, the feature it belongs to, the difficulty, and even its priority. We recommend you to start from issues labeled as `good-first-issue <https://github.com/radareorg/cutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_. These issues were tagged by us as suitable for new contributors.
|
||||
|
||||
Projects
|
||||
^^^^^^^^^^
|
||||
We use `project boards <https://github.com/radareorg/cutter/projects>`_ to gather together tasks and issues for specific features or problems. For example, we have dedicated project boards for Debugger, Hexdump widget, Decompiler widget, and High DPI support. If you are interested to take part in developing a major feature, or you want to get a broader look at a progress of a specific part in Cutter, this can be a good place to visit.
|
||||
|
||||
Milestones
|
||||
^^^^^^^^^^^^
|
||||
|
||||
When starting working on a new release, we gather together the bug and feature-requests that we consider of high-priority into a `Milestone <https://github.com/radareorg/cutter/milestones>`_. If you want to work on a feature or fix a bug that is needed and prioritized for the next release, then check out the open Milestone,.
|
||||
|
||||
|
||||
Assigning Issues
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Before choosing an issue to work on, make sure it is not assigned to anyone. If it is, you can comment and ask if this person is intended to work on the issue. Some assigned issues are abandoned by their assignee and can be picked up by other contributors.
|
||||
|
||||
|
||||
|
||||
Get familiar with the current situation
|
||||
----------------------------------------
|
||||
|
||||
Run Cutter and get familiar with how the functionality you want to modify works currently. For example, if it is a dialog, make sure you understand its role and how our users are using it. If it is a bug, try to repeat it using the instructions from the bug report.
|
||||
|
||||
.. tip::
|
||||
If you are inexperienced with binary analysis tasks, you can always ask other developers in the team about the feature and how it should be used. The team and the community will be happy to help and instruct you with everything you need to know.
|
||||
|
||||
Find the source files implementing the feature you want to work on. By doing this, practice searching code in your editor, this is an important skill. We suggest searching for files with the name of the feature. For example, if you are interested in improving the "Sections" widget, you can find the source code of this feature in `SectionsWidget.cpp` and `SectionsWidget.h`. Alternatively, you can try and look for specific unique strings that exist in the dialog, widget, or feature you want to improve. Usually, when searching the entire code base for these strings, you'll land on a file related to this feature, whether it is a ``.cpp`` file or a ``.ui`` file. From there it will be easy to navigate your way to the right place.
|
||||
|
||||
|
||||
Work on your feature or bug-fix
|
||||
-------------------------------
|
||||
|
||||
If you are experienced with such tasks, go ahead - we leave this in your hands. Otherwise, we recommend you come up with a plan for things that need to be done to solve this bug or implement this feature. Discuss your plan in the relevant issue on GitHub.
|
||||
|
||||
.. important::
|
||||
Before starting coding, make sure to get yourself familiar with our comprehensive documentation for our `coding style, conventions, and guidelines <development-guidelines.html>`_.
|
||||
|
||||
|
||||
If you don't know how to implement something, check if any of the existing code implements similar behavior in the same widget or similar widgets. If you do copy an existing code consider why it did things the way it did, the same factors might not apply in your case or the old code was poorly written from the first place.
|
||||
|
||||
Open a Pull request
|
||||
-------------------
|
||||
|
||||
When you are done, and the additions and modifications to the code are in place, commit your changes, and get your code reviewed by opening a new Pull Request. Please remember to follow the Pull Request template.
|
||||
|
||||
In the Pull Request template you will be required to add a "Test plan". For example, if you performed GUI changes, demonstrate it by posting a screenshot. Make a list of steps to be taken by the reviewers to verify that the changes are working as expected. This is also a good point to consider any potential edge-cases or different kinds of inputs if you didn't already do it while writing the code. Perform the steps you described when making the PR even if they seem trivial and you did them during development, it helps to catch any mistakes done during the final cleanup and making sure you didn't forget anything.
|
||||
|
||||
|
||||
Repeat
|
||||
-------
|
||||
|
||||
**Thank you!** You've made your very first contribution, and Cutter is better for it. But don't stop now. Go back to the first steps, as there is plenty more to do. A mentor or other developers might suggest a new issue for you to work on.
|
||||
|
||||
|
||||
More Information
|
||||
-----------------
|
||||
|
||||
.. important::
|
||||
We're always in the process of improving the information on this page for newcomers to the Cutter. Please help us by suggesting improvements and tell us about the information that this page lacks.
|
||||
|
@ -3,7 +3,6 @@ Development environment setup
|
||||
|
||||
This page contains recommendations and tips on how to better setup different IDEs for Cutter development.
|
||||
|
||||
.. contents::
|
||||
|
||||
General advice
|
||||
--------------
|
||||
@ -15,7 +14,7 @@ For most development builds, unless you are working on packaging issues, it is r
|
||||
|
||||
While `Qt Creator`_ has a builtin visual form and widget editor, not having it in other IDEs is not a major problem. It is also available as a standalone tool called Qt Designer and you can configure the file associations so that ``.ui`` files are opened using it. Depending on the ``.ui`` file and changes you want to make, it is sometimes easier to perform them by editing the ``.ui`` file as a text file. Essentially, ``.ui`` files are XML files. Most code editors should have some support for XML highlighting and possibly block folding.
|
||||
|
||||
The following instructions and recommendations assume that you have already download Cutter source and obtained required dependencies as described in :doc:`../building`
|
||||
The following instructions and recommendations assume that you have already download Cutter source and obtained required dependencies as described in :doc:`/building`.
|
||||
|
||||
Linux
|
||||
-----
|
50
docs/source/contributing/docs/getting-started.rst
Normal file
@ -0,0 +1,50 @@
|
||||
Contributing documentation to Cutter
|
||||
=======================================
|
||||
|
||||
If you reached this place you were probably looking to help and improve Cutter's documentation - Fantastic, welcome aboard!
|
||||
|
||||
As many other young projects, Cutter has a problem - it lacks comprehensive documentation and written content. Thankfully, contributing to Cutter's documentation doesn’t require you to have a deep knowledge about the internals of the project. Writing, reviewing, and editing the documentation are great ways to learn about Cutter.
|
||||
|
||||
Don’t like the way something reads? Discover some information that wasn’t documented? Your pull request will be gleefully embraced.
|
||||
|
||||
.. note::
|
||||
The documentation of Cutter is written using `Sphinx and reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. The syntax is quite straight forward and very similar to Markdown. In the future, we hope to move completely to Markdown as it is more popular.
|
||||
|
||||
|
||||
How can you help?
|
||||
-----------------
|
||||
|
||||
The following sections suggest ways you can contribute to Cutter's documentation. The list isn't complete as the possibilities are limitless.
|
||||
|
||||
|
||||
.. tip::
|
||||
Document what you wished to see. If you are a user of Cutter, try to think what things you would want to see documented when you started using the project. Sometimes, the best contributions are coming from your own needs.
|
||||
|
||||
User documentation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The documentation for users describes how to use Cutter and what the different features in Cutter do. The possibilities for contributing are endless since there are so many features that weren't even described on our docs yet. To contribute to our user documentation, all you need to do is pick a subject, widget, or functionality and document it. Describe the different visual components, how to use them, and what this feature even does.
|
||||
|
||||
Common Errors and Troubleshooting
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
As our community gets bigger, more and more people are using and installing Cutter on different setups. Naturally, different environments might cause different issues. This section in our docs aims to go over the most popular issues and errors that our users face and explain what causes these issues and how to solve them.
|
||||
|
||||
If you know of such a common issue, whether you faced it yourself or noticed it on our community chats, it will be very helpful if you could document it and possible solutions for it.
|
||||
|
||||
|
||||
Developers documentation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The documentation for Cutter developers aims to instruct new contributors on how to get started with developing to Cutter's codebase. It also describes best practices and development guidelines for all developers in the project. Think you have something to add to the developers' docs? We would love you to contribute.
|
||||
|
||||
API documentation
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The documentation for Cutter's API is an important reference for Cutter developers as well as Plugin developers. It thoroughly describes for developers how some functions and features work. While some of the functions are thoroughly documented, most of them aren't. Any help with improving these documentations will be blessed.
|
||||
|
||||
|
||||
Blog posts
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
We would love to see people writing and sharing their experiences with Cutter. Whether you are solving CTF challenges with Cutter, analyzing malware, finding vulnerabilities, or working on personal projects - we would love to see these published. If you have a personal blog, we would be proud to share and retweet your Cutter-related publications on our profiles, bringing you more engagement and followers. If you don't have a personal blog, we would love to host your publication on our community blog over at https://cutter.re/blog.
|
Before Width: | Height: | Size: 46 KiB After Width: | Height: | Size: 46 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 34 KiB |
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
Before Width: | Height: | Size: 31 KiB After Width: | Height: | Size: 31 KiB |
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
10
docs/source/contributing/translations/getting-started.rst
Normal file
@ -0,0 +1,10 @@
|
||||
Translate Cutter
|
||||
==================
|
||||
|
||||
Help Cutter by adding translations to the project!
|
||||
|
||||
Cutter is a global project with users from all around the world. We believe that Cutter should be as accessible as possible, and want our users to feel comfortable while using its interface. Providing our community an interface with their own language makes the experience of using Cutter better. Thus, Cutter supports a translation and localization mechanism powered by the `Crowdin <https://crowdin.com/project/cutter>`_ platform. We invite you to contribute and add translations to the project.
|
||||
|
||||
|
||||
.. important::
|
||||
We currently support more than 15 languages. If you need to add a language that isn't available yet, ask any developer from the team and they will happily assist you.
|
@ -1,33 +0,0 @@
|
||||
First time contributing
|
||||
=======================
|
||||
|
||||
Compile Cutter
|
||||
--------------
|
||||
The first step before starting to add code to Cutter, is to build it on your environment. Whether it is Linux, Windows, or macOS, we have you covered and detailed the instructions to compile Cutter on our :doc:`../building`. Once you are done and Cutter was built successfully, test that it works correctly and continue to the next steps.
|
||||
|
||||
|
||||
Read documentation
|
||||
------------------
|
||||
|
||||
Read :doc:`../developers-docs`.
|
||||
|
||||
Get familiar with current situation
|
||||
-----------------------------------
|
||||
|
||||
Run Cutter and get familiar with how the functionality you want to modify works currently. For example, if it is a dialog, make sure you understand its role and how our users are using it. If it is a bug, try to repeat it using the instructions from bug report. If you are inexperienced with binary analysis tasks, you can always ask other developers in the team about the feature and how it should be used. The team and community will be happy to help and instruct.
|
||||
|
||||
Find the source files implementing the feature you want to work on. By doing this, practice searching code in your editor, this is an important skill. We suggest searching for files with the name of the feature. For example, if you are interested in improving the "Sections" widget, you can find the source code of this feature in `SectionsWidget.cpp` and `SectionsWidget.h`. Alternatively, you can try and look for specific unique strings that exist in the dialog, widget or feature you want to improve. Usually, when searching the entire code base for these strings, you'll land on a file related to this feature, whether it is a `.cpp` file or a `.ui` file. From there it will be easy to navigate your way to the right place.
|
||||
|
||||
|
||||
Work on your feature or bug-fix
|
||||
-------------------------------
|
||||
|
||||
Come up with a plan for things that need to be done and discuss it in GitHub issue. Just because something was mentioned in issue description doesn't necessarily means that it is still relevant or good feature.
|
||||
If you don't know to implement something check if any of the existing code implements similar similar behavior in the same widget or similar widgets. If you do copy an existing code consider why it did things the way it did, the same factors might not apply in your case or the old code is simply bad.
|
||||
|
||||
Open a Pull request
|
||||
-------------------
|
||||
When you are done, and the code changes, additions, and modifications are in place and comitted, it is time to move forward and opening a new Pull Request. Please remember to follow the PR template upon opening a new one.
|
||||
|
||||
In the Pull Request template you will be required to add a "Test plan". For example, if you performed GUI changes, demonstrate it by posting a screenshot.
|
||||
Make a basic list of steps for checking that changes are working as expected. This is also a good point to consider any potential edge-cases or different kinds of interesting inputs if you didn't already do it while writing the code. Perform the steps you described when making the PR even if they seem trivial and you did them during development, it helps to catch any mistakes done during the final cleanup and making sure you didn't forget anything.
|
@ -40,18 +40,18 @@ Want to help the project?
|
||||
-------------------------
|
||||
|
||||
If you want to contribute to Cutter, take a look
|
||||
`here <https://github.com/radareorg/cutter/blob/master/CONTRIBUTING.md>`__
|
||||
`here <contributing>`_
|
||||
to learn how you can help improve the project!
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
:maxdepth: 3
|
||||
|
||||
shortcuts
|
||||
user-docs
|
||||
contributing
|
||||
Developer documentation <contributing/code>
|
||||
building
|
||||
common-errors
|
||||
developers-docs
|
||||
user-docs
|
||||
plugins
|
||||
api
|
||||
|
||||
|
@ -15,7 +15,7 @@ Loading and Overview
|
||||
Plugins are loaded from an OS-dependent user-level directory.
|
||||
To get the location of this directory and a list of currently loaded plugins, navigate to Edit -> Preferences -> Plugins.
|
||||
|
||||
.. image:: plugins/preferences-plugins.png
|
||||
.. image:: contributing/plugins/preferences-plugins.png
|
||||
|
||||
The plugins directory contains two subdirectories, ``native`` and ``python`` for C++ and Python plugins respectively,
|
||||
which will be created automatically by Cutter.
|
||||
@ -32,4 +32,4 @@ Creating Plugins
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
plugins/*
|
||||
contributing/plugins/*
|
||||
|
@ -11,6 +11,7 @@ Cutter is an advanced reverse engineering platform that is powered by radare2. T
|
||||
:titlesonly:
|
||||
:glob:
|
||||
|
||||
user-docs/shortcuts
|
||||
user-docs/command-line
|
||||
user-docs/menus
|
||||
user-docs/preferences
|
||||
|