Skip to content

Latest commit

 

History

History
17 lines (15 loc) · 4.7 KB

CONTRIBUTING.md

File metadata and controls

17 lines (15 loc) · 4.7 KB
Raw

Contributing

Contributions are very welcome and most will be merged, as long as the basic principles are adhered to:

  • No inclusions of Standard C++ Library's headers inside headers of this library. The STD Lib C++ may be used but only through their inclusion in your .cpp files. Exception: Utility template classes, designed to work directly on STD Lib types, like std::vector. Rationale: Long compilation times of C++ projects result from cascaded inclusions of heavy headers (like Boost) and multiple medium-heavy headers (like STD lib). If you have a great idea to contribute, but it would violate this rule, please consult it first by opening an issue. Maybe it can be still merged, when it's isolated enough. There are such rare cases in this library, where the class' utility has won, because it didn't sacrifice the overall compilation time, thanks to proper isolation (i.e. they are utility classes, rather than basic types).
  • Up to C++14, preferrably C++11 standard. Use C++03, whenever possible, although the C++03 is a very soft requirement, which I may later achieve selectively by myself. If you've got a kicka$$ code to contribute, that goes beyond C++14, it must be placed in a subproject (which I will setup TODO). The higher C++ standard project must not be a dependency of this, C++14-standard project (if it's not obvious for you, that is).
  • All code, that depends on heavy 3rd party dependencies, such as Boost, must be placed in separate subprojects, in this example: EnjoLibBoost, or EnjoLib3rd (for now) for all other 3rd party deps. The same header rule applies as with the first rule: no inclusions of 3rd party headers in our headers.
  • New functionality -> new Unit Tests please. At least some stubs thereof. The tests serve a kind of requirements engineering, therefore require just a little bit of documentation as well.
  • Any bugfix of a newly discovered bug MUST be accompanied with a reproducible regression test in a form of a Unit Test(s). If we don't stick to this rule, then we loose a valid test case and risk reintroducing the bug in future. If you can't write such test by yourself, then we'll try to do it together before merging. Note, that you can't predict all the possible corner cases while writing the code, even using well documented industry methods like ECP and BVA. I know and used these methods and it's all a utopian waste of time for me in the end, only useful if you belong to the camp of people, who want to write (or are paid for writing) just too many tests, which are in reality equivallent. OTOH, one methodology, that's very close to my heart is TDD. The TDD however assumes short compilation and linkage times. Since this is extremely rare for a typical C++ project, in practice you won't find many C++ devs, who practice TDD. Here's your chance to learn and have fun with it.
  • Tests shall not overfit the implementation. Keep in mind, that there may always be other implementations of the same algo available later, which compute the same thing eihter faster (x)or more precise or even both with a lot of risky optimisations, unlike the reference implementation. The majority of tests should not be able to distinguish between the given algo's various implementations. This allows the same test to cross check the (riskly) optimised versions against the reference implementations under the exactly same conditions.
  • When designing classes, please follow the SOLID principles.
  • Please document the intention of the code you write in the .cpp files in Doxygen syntax for the signatures, as well as please use single/double line comments of the implementation, especially for relatively odd solutions. By doing so, you show a lot of respect to other people, even if it doesn't appear so.
  • Don't take reviews personally nor emotionally :) This is all meant to be productive and fun at the same time.
  • The PRs should be transactional and small enough. Fixing unrelated code smells is welcome, but ideally only in the files being touched in given PR. And don't forget to make sure, that the fix you do is unit tested.
  • Don't be shy of any contributiuons. Anything that's somehow not fitting, will be addressed during a review anyway.
  • The new code shall have a BSD-licence (or compatible) clause at the end of each file. Any copyleft code shall go to the GPL submodule (TODO: once the module is ready. For now, a clear copyright notice is enough).
  • I might tip you for great contributions, but I can't promise this at all times, so don't feel undervalued, if I don't do it. Sometimes I may be simply outta loot.