update readme.md and add dev tips to hacking.md

HACKING.md

@@ -0,0 +1,65 @@
+# Development tips
+We have tried hard to make the process of bootstrapping this project as simple as possible.
+
+In order to build and install the project locally, make sure you have created and activated a virtual environment using `virtualenv` or `python -m venv` (for newer Python releases). Then you can just run:
+
+    make build
+
+This command will bootstrap the whole environment (pull git submodules, install dev requirements, etc.) and build the project. `make` will automatically install `imgui` in the *development/editable* mode. Then you can run some examples found in the `doc/examples` directory in order to verify if the project is working.
+
+You can install requirements manually using files `doc/requirements-***.txt`. E.g., with
+
+    pip install -r doc/requirements-dev.txt
+
+If you have any problems with building or installing the project, just ask us
+for help by creating a GitHub issue.
+
+# Function mapping
+
+The `imgui.h` file that provides the interface with the DearImGui lib is fully mapped in `imgui/cimgui.pxd`. We use a mark (`✓`/`✗`) system to estimate how many functionalities are mapped automatically. **Please edit the tick mark properly if you want to map an unmapped function**.
+
+Functions listed in the `cimgui.pxd` correspond to mappable functions for the supported version of DearImGui. Please refer to the next section for information about version syncing.
+
+# Version syncing
+
+> Pyimgui 2.0 uses DearImGui 1.82
+
+We specifically bind pyimgui releases to a specific stable version of DearImGui. Thus, when upgrading to a newer version of DearImGui, some care must be taken.
+
+First, one should update the submodule dependency to point to a specific release tag and not just get the latest commits of the `master` branch.
+
+Moreover, the `docking` branch should also be modified accordingly, such that each branch points to the correct DearImGui release. (Sync list is given in [https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228](https://github.com/pyimgui/pyimgui/issues/259#issuecomment-1039090228))
+
+When updating the submodule to a recent release, we must update the `imgui/cimgui.pxd` accordingly. This means that all new functions must be mapped with the `✗`, all depreciated functions must be indicated as such, and so on. Every flag must be properly added and documented in the `imgui/enums.pxd`, `core.pyx`, and `__init__.py`. Idem for the `internal` subpackage.
+
+> The easiest way to proceed with updates that skip several releases is to do them one by one. E.g., for going from 1.82 to 1.87, I would suggest taking each release note from DearImGui and upgrading to 1.83 first. And then, when it is fully done, update to 1.84. And so on. At each step, ensure that `cimgui.pxd` is updated and that all enums are properly added. I would also use a file diff software to check the old `imgui.h` with the new one.
+
+Since the process is very time-consuming, please refrain from taking the initiative of upgrading DearImGui before asking via an issue. We may have specific plans that you are not informed of.
+
+# Tests
+
+For running tests, you will need some additional
+requirements from `doc/requirements-test.txt`.
+
+You can run tests with:
+
+    py.test
+
+Tests of functionalities are automatically extracted from the `visual-example` part of the docstring documentation of mapped functions. We also have more in-depth tests of specific features in the `tests/` folder.
+
+# Documentation
+
+For building documentation, you will need some additional
+requirements from `doc/requirements-docs.txt`.
+
+Documentation building should be run from the `doc/source/` directory:
+
+    cd doc/source/
+
+Documentation is built using Sphinx. The command used on ReadTheDocs is
+
+    python -m sphinx -W --keep-going -T -E -b HTML -d _build/doctrees -D language=en . _build/HTML
+
+**pyimgui** provides documentation with multiple visual examples.
+Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring snippets. These examples work also as automated functional tests. Documentation is hosted on
+[pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html).

README.md

@@ -1,7 +1,7 @@
 [![completion](https://img.shields.io/badge/completion-70%25%20%28520%20of%20735%29-blue.svg)](https://github.com/pyimgui/pyimgui)
-[![Coverage Status](https://coveralls.io/repos/github/pyimgui/pyimgui/badge.svg?branch=master)](https://coveralls.io/github/swistakm/pyimgui?branch=master)
 [![Documentation Status](https://readthedocs.org/projects/pyimgui/badge/?version=dev-version-2.0)](https://pyimgui.readthedocs.io/en/latest/?badge=dev-version-2.0)
 [![Build status](https://ci.appveyor.com/api/projects/status/mr97t941p6k4c261/branch/dev/version-2.0?svg=true)](https://ci.appveyor.com/project/KinoxKlark/pyimgui/branch/dev/version-2.0)
+<!--[![Coverage Status](https://coveralls.io/repos/github/pyimgui/pyimgui/badge.svg?branch=master)](https://coveralls.io/github/swistakm/pyimgui?branch=master)-->
 
 # pyimgui
 
@@ -43,14 +43,14 @@ ImGui library. The *completion badge* shows up-to-date status of that goal.
 
 # Project distribution
 
-This project has a working build pipeline on Appveyor and Travis. It builds
+This project has a working build pipeline on Appveyor. It builds
 succesfully for all major operating systems with different architectures:
 
 * Windows (32bit & 64bit)
 * Linux (32bit & 64bit)
 * OS X (universal build)
 
-Right now we are ready to shipping the built wheels for these three systems
+Right now we are ready shipping the built wheels for these three systems
 (even for Linux using `manylinux1` wheels). The build pipeline covers multiple
 Python versions:
 
@@ -59,14 +59,7 @@ Python versions:
 * py38, pp38
 * py39, pp39
 
-__Note:__ We dropped support for py27, py33, py34, and py35 since release 2.0.
-Those were supported until release [1.4.0](https://github.com/pyimgui/pyimgui/releases/tag/1.4.0). Pypy is only supported since release 2.0.
-
-**pyimgui** provides documentation with multiple visual examples.
-Thanks to custom Sphinx extensions we are able to render GUI examples off
-screen directly from docstring snippets. These examples work also as automated
-functional tests. Documentation is hosted on
-[pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html).
+__Note:__ We dropped support for py27, py33, py34, and py35 starting from release 2.0. Those were supported until release [1.4.0](https://github.com/pyimgui/pyimgui/releases/tag/1.4.0). Pypy is only supported since release 2.0.
 
 If none of these wheels work in your environment you can install the `imgui`
 package by compiling it directly from sdist distribution using one of following
@@ -78,29 +71,12 @@ commands:
     # will compile from pre-generated C++ sources
     pip install imgui --no-binary imgui
 
+**pyimgui** provides documentation with multiple visual examples.
+Thanks to custom Sphinx extensions, we are able to render GUI examples off-screen directly from docstring snippets. These examples work also as automated functional tests. Documentation is hosted on
+[pyimgui.readthedocs.io](https://pyimgui.readthedocs.io/en/latest/index.html).
 
-# Development tips
-We have tried hard to make the process of bootstrapping this project as simple
-as possible.
-
-In order to build and install project locally, make sure you have created and
-activated virtual environment using `virtualenv` or `python -m venv` (for newer
-Python releases). Then you can just run:
-
-    make build
-
-This command will bootstrap whole environment (pull git submodules, install 
-dev requirements etc.) and build the project. `make` will automatically install
-`imgui` in the *development/editable* mode. Then you can run some examples
-found in the `doc/examples` directory in order to verify if project is working.
-
-For building documentation and running tests you will need some additional
-requirements from `doc/requirements-test.txt`.
-
-You can run tests with:
-
-    py.test
+# Contributing
+Contributions are welcomed. If you want to help us by fixing bugs, mapping functions, or adding new features, please feel free to do so and propose a pull request.
 
+Development tips and information for developers are given in [HACKING.md](HACKING.md).
 
-If you have any problems with building or installing the project just ask us
-for help by creating GitHub issue.