From 850b2c20f7448bbfbff2fa2520fb220959ab04ba Mon Sep 17 00:00:00 2001 From: Leonardo Ayala Date: Mon, 15 Apr 2024 11:07:25 +0200 Subject: [PATCH 1/2] Renamed dark and white balance buttons in the UI --- src/mainwindow.ui | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mainwindow.ui b/src/mainwindow.ui index e1379eb..67d7acb 100644 --- a/src/mainwindow.ui +++ b/src/mainwindow.ui @@ -230,7 +230,7 @@ false - new dark correction + Dark correction @@ -240,7 +240,7 @@ false - new white balance + White balance From 80846cd3de040a2a8dad625aea245be7ce36c9c6 Mon Sep 17 00:00:00 2001 From: Leonardo Ayala Date: Tue, 16 Apr 2024 19:34:41 +0200 Subject: [PATCH 2/2] Moved developer guidelines to documentation page and removed it from README.md --- README.md | 109 -------------------------- doc/source/developer_guidelines.rst | 115 ++++++++++++++++++++++++++++ doc/source/index.rst | 2 + 3 files changed, 117 insertions(+), 109 deletions(-) create mode 100644 doc/source/developer_guidelines.rst diff --git a/README.md b/README.md index 349cf8f..1f1b567 100644 --- a/README.md +++ b/README.md @@ -6,112 +6,3 @@ This software can be built following the instructions provided in out [Getting S # FAQ If you are having issues, make sure to check the [FAQ section](https://imsy.pages.dkfz.de/issi/susicam/faq.html) of our documentation. - - - ---- - -## **Developer guidelines** :computer: -
- -These guidelines are meant to help you develop code for this package: documentation, unittesting, bug fixes, features, releases, etc. (click to expand) - - - -### General rules -1. Binary files can NOT be added to the repository, ideally you should develop your code in `.cpp, .h` files. - Example of files that should NOT be added to the repository: `.png`, `.tif`, `.npy`, `.pkl`, `.dat`, `.html` - If you have doubts about the files you are committing, you can always ask for help. -2. Branch naming follows `git flow` conventions, you can find a cheatsheet with the most common commands here - [GitFlow](https://danielkummer.github.io/git-flow-cheatsheet/). - In order to initialize git flow in your environment you need to run: - - `git flow init -d` - - Before starting your `feature`, `hotfix`, etc. - you need to create a task in the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues). - After creating the task you will see a number like this `18` in the title of the task. You should use this for - naming your branch. For example: - - `git flow feature start 18-my_branch_name` - - This will create a branch with the name `feature/18-my_branch_name`, notice that `git flow` prepends `feature` to - the branch name automatically. More details on how to finish the branch can be found in the section [contributing a feature](#contributing-a-featurebug-fix) -3. You need to have implemented tests for your code before merging into develop, we use GoogleTests for that. You also need to have written documentation for your implementations. - -### Documentation :book: - -Ideally all your code should be documented, the markup used for the documentation is [**Doxygen-style**](https://www.doxygen.nl/manual/docblocks.html). -You should stick to it. The documentation can be built by doing the following. -```bash -cd doc -sudo apt install -y doxygen graphviz -pip install -U sphinx furo breathe -doxygen Doxyfile -make html SPHINXOPTS="-j4" -``` -After that, you should see a build directory where the html code is written to. - - -### Unittesting :test_tube: - -As mentioned before, your code should ideally be tested thoroughly. For this we use `unittests`. You can find examples of -it in the already created unittests in our repository. - -### Contributing a feature/bug fix :bug: -If you have doubts on how to finish your feature branch, you can always ask for help -1. Create issue on the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues), if a task does not exist yet. -2. Assign the task to you. -3. Create the `feature` branch: `git flow feature start `. - >`` has to match the following pattern: `-` -4. Update `feature` branch: `git checkout && git merge develop` -5. Run tests in `feature` branch -6. Create a merge request for your feature in gitlab, select `develop` and the destination branch and assign reviewers -7. The branch will be reviewed and automatically merged if there are no requested changes - -### Contributing a hotfix :fire: -The version tag has to match the following pattern: `v..` with `x=major, y=minor, z=patch` version number - -1. Create a task on the [SUSICAM work board](https://git.dkfz.de/imsy/issi/susicam/-/issues), if a task does not exist yet. -2. Set the task priority to high, if not done yet. -3. Assign the task to you. -4. Create the `hotfix` branch: `git flow hotfix start `. - > `` has to match the following pattern: `-` -5. Commit your hot fixes. -6. Bump the version number in the last commit. Increment the patch number of the latest version tag by one. Following files have to be touched: - * `doc/conf.py` -7. Finish the `hotfix` by specifying the version tag and the message: `git flow hotfix finish - -T -m "Release of susi package"` -8. The `hotfix` branch has been merged into `main` and `develop`. The `hotfix` branch has been deleted locally and remotely. You are now on `develop` branch, which has to be pushed. -9. Switch to `main` branch and also push it. -10. Also push the version tag: `git push origin `, or alternatively `git push --tags` -11. Change status of the task to `resolved`. - -## Preparing a release :package: -The version tag has to match the following pattern: `v..` with `x=major, y=minor, z=patch` version number - -1. Releases are tracked via [milestones](https://git.dkfz.de/imsy/issi/susicam/-/milestones). -2. Make sure that all tasks relevant for the corresponding milestone have been resolved. -3. Create a `release` branch: `git flow release start `. The version tag is the title of the milestone. -4. Perform testing on the `release` branch. - * run tests - * Fix issues on the `release` branch - * Repeat testing procedure until no errors occur -5. Update release number. Following files have to be touched: - * `doc/conf.py` -6. Finish a release: `git flow release finish -T -m "Release of susicam package"` -7. Push `develop` branch and `master` branch. -8. Push tags with `git push origin `, or alternatively `git push --tags` -9. Change status of all release-relevant tasks to resolved (if not done already). - -### Finished or deprecated branches :older_adult: - -Branches that are no longer in use or that have been merged into develop should be deleted, except persistent branches such as `documentation`. -If you followed the guidelines for finishing a feature, your feature branch should have been deleted automatically. -If you merged into develop but your branch is still there, you can delete it manually by doing - ->Make sure that your code is already in develop (before delete branches) by going to [susicam](https://git.dkfz.de/imsy/issi/susicam) and checking the develop branch - -`git branch -d ` -`git push origin --delete ` - -
diff --git a/doc/source/developer_guidelines.rst b/doc/source/developer_guidelines.rst new file mode 100644 index 0000000..6bd4dcf --- /dev/null +++ b/doc/source/developer_guidelines.rst @@ -0,0 +1,115 @@ +==================== +Developer guidelines +==================== + +These guidelines are meant to help you develop code for this package: documentation, unittesting, bug fixes, features, releases, etc. + + +General rules +============= +#. Binary files can NOT be added to the repository, ideally you should develop your code in `.py` files. + Example of files that can NOT be added to the repository: :code:`.png, .tif, .npy, .pkl, .dat, .html` + If you have doubts about the files you are committing, you can always ask for help. +#. Branch naming follows `git flow` conventions, you can find a cheatsheet with the most common commands here + `GitFlow `_. + In order to initialize git flow in your environment you need to run: + + .. code-block:: bash + + git flow init -d + + Before starting your :code:`feature`, :code:`hotfix`, etc. + you need to create a task in the `SUSICAM work board `_. + After creating the task you will see a number like this `T18` in the title of the task. You should use this for + naming your branch. For example: + + .. code-block:: bash + + git flow feature start T18-my_branch_name + + This will create a branch with the name :code:`feature/T18_my_branch_name`, notice that `git flow` prepends :code:`feature` to + the branch name automatically. More details in :ref:`contributing-a-feature`. +#. You need to have implemented tests for your code before merging into develop. +#. You need to run all the tests before merging into develop. +#. If you need some real images in order + to test your code, you can get several examples from :code:`skimage.data`, this is the preferred method. + +Documentation +============= +Ideally all your code should be documented, the markup used for the documentation is `Doxygen-style `_. You should stick to it. +To build the documentation locally and check that yours is rendered properly you need to follow the next steps. + +.. code-block:: bash + + cd doc + sudo apt install -y doxygen graphviz + pip install -U sphinx furo breathe + doxygen Doxyfile + make html SPHINXOPTS="-j4" + + +Now you can navigate to doc/build and open `index.html` to access the documentation. The documentation corresponding to the develop branch is also +hosted in online: `SUSICAM documentation `_. + +Unittesting +=============== +As mentioned before, your code should ideally be tested thoroughly. For this we use GoogleTests. You can find +examples of it in the already created unittests in our repository. + +.. _contributing-a-feature: + +Contributing a feature/bug fix +============================== +If you have doubts on how to finish your feature branch, you can always ask for help + +#. Create issue on the `SUSICAM work board `_, if a task does not +exist yet. +#. Assign the task to you. +#. Create the :code:`feature` branch: :code:`git flow feature start `. + + .. tip:: + + `` has to match the following pattern: `T-` + +#. Implement your code +#. Update :code:`feature` branch: :code:`git checkout && git merge develop`. +#. Run tests in :code:`feature` branch +#. Create a merge request for your feature in `GitLab merge request list `_, + select `develop` as the destination branch and assign reviewers. +#. The branch will be reviewed and automatically merged if there are no requested changes. + +Preparing a release +=================== +The version tag has to match the following pattern: :code:`v..` with :code:`x=major, y=minor, z=patch` version +number + +#. Create a :code:`release` branch: :code:`git flow release start `. +#. Perform testing on the :code:`release` branch. + * Run tests + * Fix issues on the :code:`release` branch + * Repeat testing procedure until no errors occur +#. Update release number. Following files have to be touched: + * `doc/conf.py` +#. Finish a release: :code:`git flow release finish -T -m "Release of package"` +#. Push :code:`develop` branch and :code:`master` branch. +#. Push tags with :code:`git push origin `, or alternatively :Code:`git push --tags` +#. Change status of all release-relevant tasks to resolved (if not done already). + + +Finished or deprecated branches +------------------------------------ +Branches that are no longer in use or that have been merged into develop should be deleted. +If you followed the guidelines for finishing a feature, your feature branch should have been deleted automatically. +If you merged into develop but your branch is still there, you can delete it manually by doing the following. + +.. tip:: + + Make sure that your code is already in develop (before delete branches) by going to `SUSICAM `_ and checking the develop branch + +.. code-block:: bash + + git branch -d + git push origin --delete diff --git a/doc/source/index.rst b/doc/source/index.rst index 75e8b2e..86d550b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -32,6 +32,8 @@ Installing dependencies, building SUSICAM and how to use SUSICAM is all introduc faq.rst + developer_guidelines.rst + Development logic ================= The SUSICAM application relies at its core on many `Qt `_ components for the GUI, while