1Bareos Developer Notes 2====================== 3 4This document is intended mostly for developers and describes how you 5can contribute to the Bareos project and the general framework of making 6Bareos source changes. 7 8History 9------- 10 11Bareos is a fork of the open source project Bacula version 5.2. In 2010 12the Bacula community developer Marco van Wieringen started to collect 13rejected or neglected community contributions in his own branch. This 14branch was later on the base of Bareos and since then was enriched by a 15lot of new features. 16 17This documentation also bases on the original Bacula documentation, it 18is technically also a fork of the documenation created following the 19rules of the GNU Free Documentation License. 20 21Original author of Bacula and it’s documentation is Kern Sibbald. We 22thank Kern and all contributors to Bacula and its documentation. We 23maintain a list of contributors to Bacula (until the time we’ve started 24the fork) and Bareos in our AUTHORS file. 25 26Contributions 27------------- 28 29Contributions to the Bareos project come in many forms: ideas, 30participation in helping people on the `bareos-users`_ email list, 31packaging Bareos binaries for the community, helping improve the 32documentation, and submitting code. 33 34Patches 35------- 36 37Patches should be sent as a pull-request to the master branch of the GitHub repository. 38A detailed description can be found in the chapter :ref:`git-workflow`. 39If you don't want to sign up to GitHub, you can also send us your patches via E-Mail in **git format-patch** format to the `bareos-devel`_ mailing list. 40 41Please make sure to use the Bareos `Automatic Sourcecode Formatting`_ 42Don’t forget any Copyrights and acknowledgments if it isn’t 100% your code. 43Also, include the Bareos copyright notice that can be found in every source file. 44 45Bug Database 46------------ 47 48We have a bug database which is at https://bugs.bareos.org. 49 50The first thing is if you want to take over a bug, rather than just make 51a note, you should assign the bug to yourself. This helps other 52developers know that you are the principal person to deal with the bug. 53You can do so by going into the bug and clicking on the **Update Issue** 54button. Then you simply go to the **Assigned To** box and select your 55name from the drop down box. To actually update it you must click on the 56**Update Information** button a bit further down on the screen, but if 57you have other things to do such as add a Note, you might wait before 58clicking on the **Update Information** button. 59 60Generally, we set the **Status** field to either acknowledged, 61confirmed, or feedback when we first start working on the bug. Feedback 62is set when we expect that the user should give us more information. 63 64Normally, once you are reasonably sure that the bug is fixed, and a 65patch is made and attached to the bug report, and/or in the Git, you can 66close the bug. If you want the user to test the patch, then leave the 67bug open, otherwise close it and set **Resolution** to **Fixed**. We 68generally close bug reports rather quickly, even without confirmation, 69especially if we have run tests and can see that for us the problem is 70fixed. However, in doing so, it avoids misunderstandings if you leave a 71note while you are closing the bug that says something to the following 72effect: We are closing this bug because... If for some reason, it does 73not fix your problem, please feel free to reopen it, or to open a new 74bug report describing the problem“. 75 76We do not recommend that you attempt to edit any of the bug notes that 77have been submitted, nor to delete them or make them private. In fact, 78if someone accidentally makes a bug note private, you should ask the 79reason and if at all possible (with his agreement) make the bug note 80public. 81 82If the user has not properly filled in most of the important fields (platform, OS, Product Version, ...) please do not hesitate to politely ask him to do so. 83The same applies to a support request (we answer only bugs), you might give the user a tip, but please politely refer him to the manual, the `bareos-users`_ mailing list and maybe the `commercial support`_. 84 85.. _bareos-users: https://groups.google.com/forum/#!forum/bareos-users 86.. _commercial support: https://www.bareos.com/en/Support.html 87 88Reporting security issues 89~~~~~~~~~~~~~~~~~~~~~~~~~ 90 91If you want to report a security-related problem, please take a look at our `security policy`_. 92 93.. _security policy: https://github.com/bareos/bareos/security/policy 94 95Memory Leaks 96------------ 97 98Use standard C++11 resource management (RAII and smart pointers) to prevent memory leaks in general. If you need to detect memory leaks, you can just use ``valgrind`` to do so. 99 100Guiding Principles 101------------------ 102 103All new code should be written in modern C++11 following the `Google C++ Style Guide`_ and the `C++ Core Guidelines`_. 104 105We like simple rather than complex code, but complex code is still better than complicated code. 106 107Currently there is still a lot of old C++ and C code in the code base and a lot of existing code violates our `do's`_ and `don'ts`_. Therefore our long-term goal is to modernize the code-base to make it easier to understand, easier to maintain and better approachable for new developers. 108 109Automatic Sourcecode Formatting 110------------------------------- 111 112All C/C++ code should be formatted properly based on the principles mentioned above. Therefore we provide a configuration file for **clang-format** that contains all formatting rules. The filename is ".clang-format" and it is located in the root directory of the bareos repo. 113 114The configuration file will be automatically found and used by clang-format: 115 116.. code-block:: bash 117 :caption: Example shell script 118 119 #!/bin/sh 120 121 #format one sourcecode file in-place 122 clang-format -i ./core/src/dird/dird_conf.cc 123 124 125Formatting exceptions 126--------------------- 127 128For some parts of code it works best to hand-optimize the formatting. We sometimes do this for larger tables and deeply nested brace initialization. If you need to hand-optimize make sure you add **clang-format off** and **clang-format on** comments so applying **clang-format** on your source will not undo your manual optimization. Please apply common sense and use this exception sparingly. 129 130Sourcecode Comments 131------------------- 132 133Use ``/* */`` for multi-line comments. 134Use ``//`` for single-line comments. 135 136Do's 137---- 138 139- write modern C++11 140- prefer simple code 141- write unit tests for your code 142- use RAII_ whenever possible 143- honor `Rule of three`_/`Rule of five`/`Rule of zero` 144- use ``std::string`` instead of ``char*`` for strings where possible 145- use `fixed width integer types`_ if the size of your integer matters 146- when in doubt always prefer the standard library over a custom implementation 147- follow the `Google C++ Style Guide`_ 148- follow the `C++ Core Guidelines`_ 149- get in touch with us on the `bareos-devel`_ mailing list 150 151.. _RAII: https://en.cppreference.com/w/cpp/language/raii 152.. _Rule of three: https://en.cppreference.com/w/cpp/language/rule_of_three 153.. _fixed width integer types: https://en.cppreference.com/w/cpp/types/integer 154.. _Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html 155.. _C++ Core Guidelines: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines 156.. _bareos-devel: https://groups.google.com/forum/#!forum/bareos-devel 157 158Don'ts 159------ 160 161avoid ``new`` 162 Starting with C++11 there are smart pointers like ``shared_ptr`` and ``unique_ptr``. 163 To create a ``shared_ptr`` you should use ``make_shared()`` from the standard library. 164 We provide a backport of C++14's ``make_unique()`` in ``include/make_unique.h`` to create a ``unique_ptr``. 165 If possible use ``unique_ptr`` instead of ``shared_ptr``. 166 167avoid ``delete`` 168 You should use the RAII_ paradigm, so cleanup is handled automatically. 169 170don't transfer ownership of heap memory without move semantics 171 No returning of raw pointers where the caller is supposed to free the resource. 172 173don't use C++14 or later 174 Currently we support platforms where the newest available compiler supports only C++11. 175 176don't use C string functions 177 If you can, use ``std::string`` and don't rely on C string functions. 178 179don't use the bareos replacements for C string functions. 180 These are deprecated. 181 182avoid the ``edit_*()`` functions from ``edit.cc`` 183 Just use the appropriate format string. 184 This will also avoid the temporary buffer that is required otherwise. 185 186avoid pool memory allocation 187 The whole allocation library with ``get_pool_memory()`` and friends do not mix with RAII, so we will try to remove them step by step in the future. 188 Avoid in new code if possible. 189