Update developer documentation (#2076)

* Update developer documentation
* Create a separate section for developer documentation
* Add first-time contribution guide

CONTRIBUTING.md

@@ -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/code.html
+Please follow our contribution guidelines: https://cutter.re/docs/dev-doc.html
 
 ## Contributing to the documentation
 

docs/source/dev-doc.rst

@@ -1,10 +1,18 @@
-Contributing
-============
+Developer documentation
+=======================
 
 This page shows some hints about the coding conventions.
 
-Coding advices
---------------
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   dev-doc/*
+   crash-handling-system
+
+
+Cutter coding advices
+---------------------
 
 CutterCore class
 ~~~~~~~~~~~~~~~~
@@ -56,11 +64,8 @@ Make sure to connect the ``CutterCore::seekChanged(RVA offset)`` signal
 so your widget refreshes its output when radare2 seek is modified
 (switching to another function, etc.).
 
-General coding guidelines
--------------------------
-
 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,7 +101,7 @@ In contrast to the official guidelines of Qt, in Cutter we always use curly brac
 
 
 Includes
-^^^^^^^^
+~~~~~~~~
 
 Strive to include only **required** definitions inside header files.
 This will avoid triggering additional unnecessary compilations.
@@ -127,7 +132,7 @@ Finally, include the standard C++ headers you need.
 Includes must be sorted by alphabetical order.
 
 Docstrings
-^^^^^^^^^^
+~~~~~~~~~~
 
 Our API reference is generated using Doxygen, so when it comes to
 function documentation, please use the following format:
@@ -140,7 +145,7 @@ function documentation, please use the following format:
    virtual void accumulate(RefreshDeferrerParams params) =0;
 
 Loops
-^^^^^
+~~~~~
 
 We use the C++11 foreach loop style, which means any “foreach” loop should
 look like:
@@ -152,7 +157,7 @@ look like:
    }
 
 nullptr
-^^^^^^^
+~~~~~~~
 
 Please do not use ``0`` nor ``Q_NULLPTR``, only use ``nullptr``.
 
@@ -163,7 +168,7 @@ Example:
    QObject *object = nullptr;
 
 Connecting signals
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 To connect a signal to a slot, this is the preferred syntax:
 
@@ -171,7 +176,11 @@ To connect a signal to a slot, this is the preferred syntax:
 
    connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);
 
-The main reason is that this syntax allows the use of lambda functions.
+This syntax performs compile-time type checks and allows the use of lambda
+functions. Other approaches for connecting signals silently break at runtime.
+
+General coding advices
+----------------------
 
 Functions documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -213,3 +222,11 @@ In order to update one submodule individually, use the following code:
    cd ..
    git add radare2
    git commit -m "Update radare2 submodule"
+
+
+Useful resources to learn more about Qt development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `Signals & Slots <https://doc.qt.io/qt-5/signalsandslots.html>`__
+* `Model/View Programming <https://doc.qt.io/qt-5/model-view-programming.html>`__ - read this if you are going to work with list or table-like widgets
+* `QAction <https://doc.qt.io/qt-5/qaction.html#details>`__

docs/source/dev-doc/first-time.rst

@@ -0,0 +1,33 @@
+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:`../dev-doc`.
+
+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.

docs/source/index.rst

@@ -50,7 +50,7 @@ to learn how you can help improve the project!
    shortcuts
    building
    common-errors
-   code
+   dev-doc
    plugins
    api