Skip to content

Latest commit

 

History

History
105 lines (81 loc) · 6.09 KB

CONTRIBUTING.md

File metadata and controls

105 lines (81 loc) · 6.09 KB
Raw

Contributing Guidelines

Bug reporting

Open an issue at GitHub issue tracker. Before doing that, ensure the bug was not already reported or fixed in master branch. Describe a problem and, if necessary, provide minimal code needed to reproduce it.

Note that macOS compatibility issues are not considered bugs. dlib intentionally doesn't support macOS anymore. Read more here.

Bugs that have not been reproduced or discussed for 6 months or longer are marked as wontfix and closed.

We also use several other labels:

  • Breaking change. Self-descriptive: an improvement that breaks backward compatibility
  • Bug. A bug that should be fixed without API change
  • Enhancement. A non-breaking improvement of existing functionality (optimization or a new feature)
  • Missing. Appears when existing functionality is removed due to regressions and needs to be rewritten, or when some implementation is not complete
  • New functionality. Self-descriptive: a new functionality request.

Bug fixing

Open a new GitHub pull request with your patch. Provide a description of the problem and solution. Follow our code style. Please, try to avoid solutions that break library API and semantics - such changes should be made very carefully. If the problem can't be solved without breaking changes, explicitly state that in the description.

Implementing new features

Before writing a new module, familiarize yourself with project philosophy and best practices. Despite being a general-purpose library, dlib is not a place for rarely used or too domain-specific code. In most cases it's better to start a new library instead of pushing new modules to dlib. Only in case you find yourself constantly reusing some generic functionality in different projects it may be reasonable to propose such code to dlib. It may be a data structure, sorting algorithm, data compression method, image file decoder, communication protocol, or anything of that sort.

New code should at least:

  • work under Windows and POSIX systems and provide platform-agnostic API
  • support x86 and x86_64 targets
  • not rely on third party libraries other than system API
  • follow dlib's code style
  • use transparent dynamic memory allocations. Ideally the code should not allocate at all or rely on user for that. If internal dynamic allocations can't be avoided, they should be done with dlib.core.memory or dlib.memory. Direct garbage collector usage is discouraged
  • follow dlib's best practices, making use of ownership, containers, streams, exceptionless error handling and filesystem abstraction
  • not violate copyright/licensing. When adapting third-party code, make sure that it is compatible with Boost Software License 1.0.

Code style and standards

dlib follows D style. Essential rules are the following:

  • Use spaces instead of tabs. Each indentation level is 4 spaces
  • Opening curly bracket should be on a new line (Allman style)
  • Functions and variables should be in camelCase
  • Types, constants and enums should be in PascalCase
  • Module names should be in lowercase.

All modules in dlib should belong to a package (dlib.core, dlib.math, dlib.image, etc.). Keep package and module names short and informative. Modules with related functionality can be combined to subpackages (such as dlib.image.io). Provide a package import module (package.d with public imports) for each subpackage.

Each D module should start with a Boost license block prepended with a copyright notice:

/*
Copyright (c) 2023 <author's name here>

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization
obtaining a copy of the software and accompanying documentation covered by
this license (the "Software") to use, reproduce, display, distribute,
execute, and transmit the Software, and to prepare derivative works of the
Software, and to permit third-parties to whom the Software is furnished to
do so, all subject to the following:

The copyright notices in the Software and this entire statement, including
the above license grant, this restriction and the following disclaimer,
must be included in all copies of the Software, in whole or in part, and
all derivative works of the Software, unless such copies or derivative
works are solely in the form of machine-executable object code generated by
a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/

Documenting

It is not strictly necessary to document code, but if you do, use ddoc syntax. Each documented module should be accompanied by a description block (if you don't do that, documentation generators may ignore the module):

/**
 * <One-line description of the module>
 *
 * Description:
 * <more in-depth information (optional)>
 *
 * Copyright: Your Name 2023.
 * License: $(LINK2 https://boost.org/LICENSE_1_0.txt, Boost License 1.0).
 * Authors: Your Name
 */
module dlib.something.something;

Testing

It is advisable to write unit tests for new code, if they can be written. Sometimes functionality needs particular external environment or special conditions to run; in these cases tests are not required.

It is recommended to add one unittest block per function, method, or class. Test block should be formatted in the following way:

///
unittest
{
}