Developers guide

Checklists for developing new things in Corrade itself.

This guide is meant mainly for core Corrade developers to avoid forgetting about things. If you are contributing a pull-request, you can use these checklists as a guide and save the maintainers a bit of work — but you are not strictly required to follow them to the point.

Checklist for adding / removing a library

  1. Add a CORRADE_WITH_LIBRARYNAME CMake option to:
    • root CMakeLists.txt (if it has some inter-library dependencies, update the others / convert them to cmake_dependent_option(), adding NOT CORRADE_WITH_LIBRARYNAME to their condition — note the conditions are ANDed so they need to be specified in reverse)
    • the list in doc/building.dox (and similar files in other repos)
  2. Update FindCorrade.cmake (or similar in other repos):
    • mention the new lib in the list of components in the docs
    • if it has some inter-library dependencies, add a corresponding _CORRADE_${_COMPONENT}_DEPENDENCIES entry
    • add its name to the _CORRADE_LIBRARY_COMPONENTS regex
    • add a new elseif(_component STREQUAL LibraryName) section with special setup of includes or dependencies or explicitly say # No special setup for LibraryName library
  3. Add the library to the list in doc/corrade-cmake.dox
  4. Add a conditional add_subdirectory() to src/Corrade/CMakeLists.txt
  5. Create a new src/Corrade/LibraryName/CMakeLists.txt, copy over up-to-date license header from other CMake files, add your name to it and populate it:
    • add source files to CorradeLibraryName_SRCS variable
    • add installable headers to CorradeLibraryName_HEADERS variable
    • add private headers to CorradeLibraryName_PRIVATE_HEADERS variable (if any)
    • if the test needs some extra setup (such as e.g. CORRADE_NO_ASSERT enabled for particular files), create a new CorradeLibraryNameObjects OBJECT library with files that can be compiled the same way in both cases to speed up compilation
    • verify that the add_library() command references all input files (needed so QtCreator lists all project files properly)
    • verify that debug postfix is set (set_target_properties(CorradeLibraryName PROPERTIES DEBUG_POSTFIX "-d"))
    • verify that folder is set for all libraries and OBJECT libraries to avoid cluttering project tree view in IDEs (set_target_properties(CorradeLibraryName PROPERTIES FOLDER "Corrade/LibraryName"))
    • verify that target installation is done in proper places (separate RUNTIME / LIBRARY / ARCHIVE destinations)
    • verify that set_target_properties(CorradeLibraryName PROPERTIES VERSION ${CORRADE_LIBRARY_VERSION} SOVERSION ${CORRADE_LIBRARY_SOVERSION}) is done in case CORRADE_BUILD_STATIC is not set
    • verify that set_target_properties(CorradeLibraryName PROPERTIES POSITION_INDEPENDENT_CODE ON) is done in case CORRADE_BUILD_STATIC_PIC is set
    • verify that add_library(Corrade::LibraryName ALIAS CorradeLibraryName) (or equivalent) is added to make the library visible for CMake subprojects
  6. Create a new src/Corrade/LibraryName/Test/ directory:
    • add a CMakeLists.txt with pre-populated license header, add your name to it
    • conditionally add_subdirectory() it if CORRADE_BUILD_TESTS is enabled
  7. Create a new src/Corrade/LibraryName/LibraryName.h header for forward declarations (if needed), add a file-level doc block with Forward declarations for the @ref Corrade::LibraryName namespace as brief docs
  8. Create a new src/Corrade/LibraryName/visibility.h header with CORRADE_LIBRARYNAME_EXPORT and CORRADE_LIBRARYNAME_LOCAL macros by copypasting it from another library:
    • adapt #ifdef CorradeLibraryName_EXPORTS so it matches CMake target name
    • if the library is combined from an OBJECT library, add its name to the above #ifdef as well (and then explicitly add target_compile_definitions(ĆorradeLibraryNameObjects PRIVATE "CorradeLibraryNameObjects_EXPORTS") to CMakeLists.txt in case CORRADE_BUILD_STATIC is not set)
  9. Mention the directory and namespace in doc/namespaces.dox, basically copy-pasting the following from existing documentation:
    • directory-level doc block referencing the namespace
    • namespace-level doc block mentioning the CORRADE_WITH_LIBRARYNAME option, dependencies (if any) and a code snippet showing how to use it with CMake
  10. Code and test the rest of the library, see Checklist for adding / removing a new source / header file and Checklist for adding / removing a symbol for more information
  11. Add the CORRADE_WITH_LIBRARYNAME option to all files in package/ directory, explicitly saying either ON or OFF based on platform support:
    • all package/archlinux/PKGBUILD* files (and the AUR package(s))
    • the package/debian/rules file (watch out, tabs!)
    • the package/gentoo/ *.ebuild file
    • the package/homebrew/ *.rb file (watch out, Ruby!)
    • all package/ci/appveyor-*.bat files (^ is a line continuation)
    • all package/ci/*.sh files (\ is a line continuation)
  12. If the library has dependencies:
    • make sure they are mentioned in the library documentation
    • make sure they are mentioned in building and CMake docs
    • make sure they are mentioned in CREDITS.md
    • make sure CircleCI and AppVeyor downloads them (based on platform support)
  13. Mention the library in doc/corrade-changelog.dox
  14. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the namespace and directory docs, fix suspicious things, look also in the building and cmake docs
  15. Build a coverage build (package/archlinux/PKGBUILD-coverage), or abuse the CI for that later
  16. Push to a temporary branch (e.g., next)
  17. Iterate until the CIs are green and the code coverage is good enough
  18. Merge to master

In order to remove a library, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding / removing a plugin

Similarly to Checklist for adding / removing a library except points 2 and 5, with:

  1. Update FindCorrade.cmake (replaces point 2 in Checklist for adding / removing a library):
    • mention the new plugin in the list of components in the docs
    • add its name to the _CORRADE_PLUGIN_COMPONENTS regex
    • add a new elseif(_component STREQUAL PluginName) section with special setup of includes or dependencies or explicitly say # PluginName has no dependencies
  2. Create PluginName.conf and list all plugin dependencies (if any). The file has to be present even if empty.
  3. Create pluginRegistration.cpp by copypasting it from another plugin and adapting plugin name and plugin interface string. It's needed to be in a separate file that gets compiled only to the plugin library, not to the test library.
  4. Create configure.h.cmake for plugin-specific information about whether the library was built as static or not
  5. Create a new src/CorradePlugins/PluginName/CMakeLists.txt, copy over up-to-date license header from other CMake files and populate it (replaces point 5 in Checklist for adding / removing a library):
    • add source files to PluginName_SRCS variable
    • add installable headers to PluginName_HEADERS variable
    • add private headers to PluginName_PRIVATE_HEADERS variable (if any)
    • create a PluginNameObjects library that contains all files that are common for the plugin library and test library (usually everything except pluginRegistration.cpp), add a target_compile_definitions(PluginNameObjects PRIVATE "PluginNameObjects_EXPORTS") for it
    • use add_plugin() command (which is aliased to either corrade_add_plugin() or corrade_add_static_plugin()) to create the PluginName library, use ${CORRADE_PLUGINS_*_DEBUG_BINARY_INSTALL_DIR} / ${CORRADE_PLUGINS_*_RELEASE_BINARY_INSTALL_DIR} and ${CORRADE_PLUGINS_*_DEBUG_LIBRARY_INSTALL_DIR} / ${CORRADE_PLUGINS_*_RELEASE_LIBRARY_INSTALL_DIR} variables that correspond to given plugin interface
    • verify that both add_library() and add_plugin() commands reference all input files (needed so QtCreator lists all project files properly)
    • verify that folder is set for the OBJECT library and the test library to avoid cluttering project tree view in IDEs (set_target_properties(PluginNameObjects PROPERTIES FOLDER "CorradePlugins/PluginName")) — for the plugin library it's done automatically inside add_plugin()
    • verify that set_target_properties(PluginName PROPERTIES POSITION_INDEPENDENT_CODE ON) is done in case CORRADE_BUILD_STATIC_PIC is set
    • verify that add_library(Corrade::PluginName ALIAS PluginName) (or equivalent) is added to make the library visible for CMake subprojects
  6. If there is more than one interface header (other than just PluginName.h being installed), add a new visibility.h header. Otherwise put the visibility macros directly in PluginName.h.

In order to remove a plugin, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding / removing a plugin interface

In order to remove a plugin interface, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding / removing a tool

In order to remove a tool, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding / removing an example

  1. Add a new src/examples/name directory, copy up-to-date UNLICENSE headers from other files in the repo
  2. Verify that src/examples/name/CMakeLists.txt contains cmake_minimum_required(), project() and all cmake_policy() commands so it can be used as a top-level project level
  3. Add a new doc/name.dox page with @brief, @m_footernavigation and @page name equivalent to filename, describe what the example is doing
  4. Add a new examplename-source section with:
    • link to GitHub
    • referencing all textual example sources as - @ref example-name/file.ext "file.ext"
    • breadcrumb and navigation setup for all example sources as @example example-name/file.ext @m_examplenavigation{examples-example-name,example-name/} @m_footernavigation
  5. Update doc/corrade-example-index.dox and list the example there
  6. Mention the example in doc/corrade-changelog.dox
  7. Push to a temporary branch (e.g., next or ports-next)
  8. Iterate until the CIs are green
  9. Merge to master / ports

In order to remove an example, be sure to touch all places mentioned above, but in inverse.

Checklist for adding / removing a new source / header file

  1. Copy over a up-to-date license header (note that example code uses UNLICENSE instead of MIT) and add your name + year to it, if not already there
  2. Add a @file-level documentation block, with @brief listing all classes, functions, typedefs, enums, macros etc. that are in the file
  3. Add the file to corresponding *_SRCS, *_HEADERS, *_PRIVATE_HEADERS list in CMakeLists.txt
  4. If applicable, add a new test class file in the Test/ directory
    • name it FileNameTest.cpp, put a class named FileNameTest inside, wrapped in a Test subnamespace of the original file namespace
    • use corrade_add_test() to add it to tests
    • if some tests need GL context, add a separate test with GLTest suffix, wrapping the corresponding corrade_add_test() in if(BUILD_GL_TESTS)
  5. Populate the file, see Checklist for adding / removing a symbol and Coding style for more information.
  6. Mention the new functionality in doc/corrade-changelog.dox
  7. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the relevant docs and fix suspicious things
  8. Build a coverage build (package/archlinux/PKGBUILD-coverage), or abuse the CI for that later
  9. Push to a temporary branch (e.g., next)
  10. Iterate until the CIs are green and the code coverage is good enough
  11. Merge to master

In order to remove a file, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding / removing a symbol

  1. If the symbol is standalone (i.e., not member of a class), list it in the @file-level @brief docs
  2. Document it
  3. Add a test for it to corresponding file, verify the test gets actually run
  4. Mention the new functionality in doc/changelog.dox (and similar files in other repos)
  5. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the relevant docs and fix suspicious things
  6. Build a coverage build (package/archlinux/PKGBUILD-coverage), or abuse the CI for that later
  7. Push to a temporary branch (e.g., next)
  8. Iterate until the CIs are green and the code coverage is good enough
  9. Merge to master

In order to remove a symbol, be sure to touch all places mentioned above, only in inverse — but usually deprecate first.

Checklist for adding a new CMake documentation page

  1. Add a doc/pagename.dox file, copy up-to-date license header and add your name + year to it, if not already there
  2. If the page is top-level, list it in doc/00-page-order.dox to ensure it gets listed at a proper place
  3. If the page is not top-level, list it using @subpage in its parent page and add @m_footernavigation for automatic linking to parent and prev/next pages
  4. Add a @brief documentation, if applicable
  5. Populate it, see Coding style for more information
  6. Mention the new page in doc/changelog.dox (and similar files in other repos)
  7. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the relevant docs and fix suspicious things
  8. Push to master

Checklist for deprecating a feature

  1. If the feature is publicly exposed, think about the best way of deprecation that preserves source compatibility:
    • Add a compatibility typedef / using for a renamed symbol, marking it with CORRADE_DEPRECATED() / CORRADE_DEPRECATED_ALIAS()
    • Add a compatibility header for a renamed include, including the original file from it and marking it with CORRADE_DEPRECATED_FILE()
    • Add a compatibility inline function for a function that got renamed or its arguments changed, mark it with CORRADE_DEPRECATED()
    • Add a compatibility enum value for a value that got renamed or deleted, mark it with CORRADE_DEPRECATED_ENUM()
    • Don't ever change semantics of function arguments without changing the function signature. That would silently break with no possibility to let the user know.
    • Function return type changes are hard. One possibility is working around that by returning a wrapper type that's implicitly convertible to both the old and new type, another is introducing a differently named function instead. The last resort is breaking the API without preserving backwards compatibility — but that makes people angry, so avoid that if possible.
  2. Add just a @brief @copybrief from the replacement functionality together with a @deprecated line to the deprecated feature
  3. Reference the replacement functionality in both the deprecation macro and in the @deprecated line to make porting easier
  4. Ensure the deprecated symbol is wrapped in #ifdef CORRADE_BUILD_DEPRECATED,
  5. Ensure deprecated files #error in case they get used in non-deprecated build, ensure they are not installed in non-deprecated builds
  6. Build all tests and dependent projects and verify that:
    • using the old functionality still compiles and works as intended
    • deprecation warnings are emitted in proper places
  7. Upon verifying the above, start updating dependent code
  8. Mention the deprecated API in the deprecation section of doc/corrade-changelog.dox
  9. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the relevant docs and fix suspicious things
  10. Push to a temporary branch (e.g., next)
  11. Iterate until the CIs are green
  12. Merge to master
  13. If possible, trigger builds of dependent projects (where they are still using the old API) and verify they are still green (and red in non-deprecated build)
  14. Update dependent projects

Checklist for removing a feature

  1. Check that it was in deprecated state for more than a year with at least one release in between. Check that no important clients depend on it anymore. If not, wait a bit more.
  2. Remove relevant blocks wrapped in #ifndef CORRADE_BUILD_DEPRECATED, remove relevant deprecated files and update CMakeLists.txt
  3. Mention the removed API in the compatibility section of doc/changelog.dox (or similar files in other repos)
  4. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings — sometimes it happens that a deprecated API is still being referenced
  5. Push to a temporary branch (e.g., next)
  6. Iterate until the CIs are green
  7. Merge to master
  8. If possible, trigger builds of dependent projects and verify they are still green (or wait for the scheduled builds)

Checklist for adding, removing or updating a dependency

  1. Verify that there are no important clients stuck on the old version with no easy way to upgrade
  2. In case of CMake:
    • it's usually possible to jump more than one version, check what's the version on the oldest supported system
    • bump all cmake_minimum_required() in all repos
    • remove cmake_policy() calls that are not needed anymore
    • remove old workarounds, check changelogs for functionality that can be used now
    • update building docs to say what version is required now
    • add an entry to the dependencies section in doc/changelog.dox
    • update package/ci/*.yml to download a newer version
    • look for all mentions of the old version and remove them, grep for CMAKE_VERSION in all projects and remove what's obsolete
  3. In case of a compiler:
    • remove everything related to CORRADE_GCCXY_COMPATIBILITY of the old version, if applicable
    • update building docs to say what version is required now
    • add an entry to the dependencies section in doc/changelog.dox
    • update files in package/ci/ to use a newer version
  4. In case given dependency is external:
    • Create a dedicated Find*.cmake module and does not have a builtin one in CMake
    • update packages in package/ to depend on the new library
    • update files in package/ci/ to install it
  5. In case given dependency is single-file:
    • verify it's reasonably small (<50kB is okay, nlohmann/json is a prime example of not okay)
    • add it to src/external/ without any modifications except for trailing whitespace cleanup
    • add it in a separate Git commit, mentioning its version (or Git hash) for easier upgrades later
  6. Update CREDITS.md of affected repo to mention the added/removed dependency, its homepage and its license

In order to remove a dependency, be sure to touch all places mentioned above, only in inverse.

Checklist for adding or removing a port

  1. Add a new CORRADE_TARGET_* CMake variable:
    • to root CMakeLists.txt, which either gets enabled automatically based on system introspection or is exposed through a option() command
    • to the list of variables extracted out of configure.h in modules/FindCorrade.cmake
  2. Add a CORRADE_TARGET_* preprocessor variable:
    • add it as a #cmakedefine macro to src/Corrade/configure.h.cmake
    • add documentation for it to src/Corrade/Corrade.h
    • mention it in modules/FindCorrade.cmake docs
    • mention it in doc/corrade-cmake.dox and doc/building-corrade.dox
  3. Add a new CircleCI / AppVeyor matrix build for this port (or update existing)
  4. Add a new PKGBUILD-* file in package/archlinux for testing (or update existing)
  5. Enable or disable functionality using if(CORRADE_TARGET_*) in CMake and #ifdef CORRADE_TARGET_* in C++
  6. Mention the new stuff in doc/corrade-changelog.dox
  7. Push to a temporary branch (e.g., next)
  8. Iterate until the CIs are green
  9. Merge to master

In order to remove a port, be sure to touch all places mentioned above, only in inverse.

Checklist for adding / removing a CPU instruction set

  1. Add a new CORRADE_TARGET_FOO preprocessor variable to Corrade.h:
    • With relevant documentation pointing ideally to a Wikipedia page describing the instruction set
    • Mentioning the GCC/Clang -m option that enables it and the MSVC equivalent, if any, or the closest /arch: option that implies it
    • Linking to related other CORRADE_TARGET_* variables, or saying it's a superset of / implied by another
    • Mentioning possible caveats (like with LZCNT having a dangerous BSR fallback)
  2. Add detection into configure.h.cmake
    • On GCC / Clang it's usually a preprocessor variable in a form of __FOO__, verify with echo | gcc -dM -E -mfoo | grep FOO
    • If it's a superset of / implied by another, verify that the other preprocessor variables are set / imply this option as expected
    • Cross-check with Clang and if it has a different behavior drop the implication
    • On MSVC just assume it's enabled by the option that implies it, as there it's harder to verify
    • Special-case clang-cl under the MSVC branch, reusing the __FOO__ check for it
    • Add a case into TargetTest::cpu() verifying that it correctly implies / is implied by other target macros, or if independent that it's set only if the overarching platform macro such as CORRADE_TARGET_X86 is set as well.
  3. Add a new FooT tag type into Cpu.h
    • Roughly at the place where it historically appeared among other extensions (e.g. Cpu::PopcntT is after Sse42T and before AvxT but new AVX-512 extensions would go at the end)
    • If a superset of / implied by another, wire it into the class hierarchy (like e.g. Cpu::AvxT), otherwise keep it standalone (like e.g. Cpu::PopcntT)
    • Make the minimal documentation only link to the tag instance
  4. Add a TypeTraits<FooT> entry. Its value is important for proper overload resolution:
    • If it's in a hierarchy, renumber the other indices so it's larger than everything before it and smaller than everything after. Worst case, if the hierarchy becomes larger than 16 items, the ExtraTagBitOffset may need to get increased.
    • If it's not, ExtraTagCount may need to get updated to account for the new extra tag. You'll get static assertions if the tag value is too small.
  5. Add a new Foo tag:
    • Position matching the order in which the tag types were defined
    • Documentation similar to the CORRADE_TARGET_FOO docs, including the Wikipedia link and potential caveats
    • Mentioning it's either a superset of / implied by another (like e.g. Cpu::Avx) or an "extra" (like e.g. Cpu::Popcnt)
    • Linking to relevant other tags and corresponding CORRADE_TARGET_FOO and CORRADE_ENABLE_FOO variables
    • List it in the right place in the Utility::Debug output operator in Cpu.cpp — "extra" tags go after the base ones
    • If it seems like a reasonable addition, expand the doc/cpu.dot graph with the new tag
  6. Wire it into compile-time detection:
  7. Wire it into runtime detection:
    • For x86 find the right CPUID bit, order the branch among checks for surrounding bits
    • For ARM on Linux and Android check for a corresponding HWCAP bit, in some cases it may need to read the AT_HWCAP2 entry as well which has support further limited – see docs in the code for more information.
    • For ARM on macOS / iOS check the corresponding sysctlbyname() value
    • For WebAssembly there's no runtime detection yet. Check if anything happened with the feature detection proposal.
    • List it in Cpu::runtimeFeatures() docs, if it's depending on AVX like e.g. Cpu::Bmi1 on x86 and the dependency isn't obvious, mention that as well
  8. Add a new CORRADE_ENABLE_FOO macro:
    • With a corresponding __attribute__((__target__("foo"))), mention the matching -m option in the docs
    • If the instruction set works on clang-cl without having to define anything, then add the attribute also for clang-cl (like e.g. CORRADE_ENABLE_SSE42), if it doesn't then explicitly exclude clang-cl such as with CORRADE_ENABLE_LZCNT or CORRADE_ENABLE_AVX512F. Reflect that in the documentation — either saying that it expands to the target attribute also on clang-cl, or that it isn't defined there ever.
    • Verify and mention the special case with CORRADE_TARGET_FOO
    • If it's a superset of / implied by any other -m option (as discovered when implementing the CORRADE_TARGET_FOO detection), mention that in the docs – but only if it's consistent for GCC and Clang.
    • Add a _CORRADE_ENABLE_FOO variant for the GCC multiple target attribute workaround – one empty for when CORRADE_TARGET_FOO is defined and one just the string with a comma after ("foo",)
  9. Add a test for the CORRADE_ENABLE_FOO macro:
    • New callInstructionFor() variant for given tag type
    • Annotated with the "function variant" of the macro (thus CORRADE_ENABLE(FOO)) and also with an #ifdef for the macro around. The function variant should be used in order to test both the _CORRADE_ENABLE_FOO macro (on Clang before version 8 and GCC) and CORRADE_ENABLE_FOO (elsewhere).
    • Ideally using just that instruction alone (such as is the case with POPCNT), if not then try to use an instruction set that's implied by it so it doesn't need a second CORRADE_ENABLE_*. Clearly mark which expression uses the tested instruction set. It should verify something nontrivial (so not just a load/store) and return a non-zero value.
  10. Be sure to build & run on weird / broken compilers such as GCC 4.8 or clang-cl:
    • In case of GCC 4.8 the Utility/Intrinsics*.h headers may need to get expanded to correctly pull in the intrinsics without requiring -mfoo globally, see their code for more info.
    • Otherwise, if the new instruction set is pulled in by one of these headers already, update their docs to list it as well.
  11. Run CpuTest to verify everything:
    • Compile-time detection (test with a -march=native build or equivalent)
    • Runtime detection, ideally on multiple platforms (AMD/Intel for x86, phone + Apple M1 + CircleCI for ARM...)
    • CORRADE_ENABLE_* macro (that a corresponding enableMacros() test case is run and gives a reasonable result, use CircleCI for AVX-512 and new ARM extensions if not available locally)
    • If the instruction set isn't detected as supported on a target, verify that calling it crashes (temporarily comment out the CORRADE_SKIP() in enableMacros())
  12. List the new CORRADE_TARGET_FOO, CORRADE_ENABLE_FOO variables and the Cpu::Foo tag in doc/changelog.dox
  13. Check the output of CpuTest CI jobs for sanity:
    • Especially differences between Linux, Windows and macOS
    • Between x86, ARM and WebAssembly
    • Docker CircleCI x86 and ARM jobs tend to have very recent hardware, OTOH macOS jobs have outdated Intel CPUs without AVX2, the output should correspond to that

Checklist for uploading documentation

  1. (Optionally) remove build/doc-public to get rid of stale files
  2. Verify there are no untracked files, modifications or branches different than master checked out that could mess up the docs
  3. Run dox2html5.py on Doxyfile-public, look for suspicious warnings
  4. Upload contents of build/doc-public/html/ to doc/corrade-new/ and remove doc/corrade-old/ if any
  5. Once the upload is finished, rename doc/corrade/ to doc/corrade-old/ and doc/corrade-new/ to doc/corrade/
  6. Quickly check that the docs still look as they should, if not, revert the backup and try again

Checklist for merging a PR

  1. After the public round of review, pull the changes locally to a temporary branch (i.e., next)
  2. Verify a coverage build, verify that there are no compiler warnings
  3. Go over and fix issues that slipped through cracks in the public review
  4. Verify the contributor is mentioned in all relevant license headers, add if necessary
  5. Add the contributor to CREDITS.md, if not already there
  6. Update doc/corrade-changelog.dox, if not already done
  7. Build documentation:
    • run dox2html5.py on Doxyfile-mcss and verify there are no new warnings
    • eyeball the relevant docs and fix suspicious things
  8. Push to a temporary branch (e.g., next)
  9. Iterate until the CIs are green
  10. Merge to master, put a "thank you" comment to the PR, explaining additional changes if necessary

Checklist for creating/updating a single-header lib

This assumes the magnum-singles repository is cloned next to the corrade repository.

  1. Create/update a driver file in src/singles/, if needed
  2. Update src/singles/generate.sh, if needed
  3. Run src/singles/generate.sh, regenerating all headers
  4. Check git diff for suspicious changes.
    • no -dirty suffix in revision IDs
    • no preprocessed LoC being over 10k
  5. If nothing changes except for revision IDs in the "Generated from" lines, there's no need to update given file. Otherwise:
    • Ensure the working copy is clean with all commits pushed to master so the generated revision IDs are stable. If not, commit and push all changes first and regenerate the headers.
    • Then, write up a changelog entry in affected files, taking the revision IDs from files generated earlier. Don't commit anything, otherwise the revision ID changes again.
    • Then, generate again. This will make the changelog entry have the same revision ID as the "Generated from" line.
    • Commit that into the magnum-singles repository and ensure the CI passes.
    • After that, commit the changelog entry.
  6. In case of new header-only libraries:
    • Commit & push all changes that are needed elsewhere, except for the new file itself (and related doc updates, etc.)
    • Generate to get an revision ID.
    • Write an "Initial release" changelog entry using the generated revision ID.
    • Generate again and verify the IDs still match.
    • Commit that into the magnum-singles repository, including a new test:
      • new file in magnum-singles/test, named after the header, including the header and doing a simple operation that results in return 0
      • new entry in magnum-singles/package/ci/*.yml, compiling the new test Ensure the CI runs on the new file and passes.
    • After that, commit the new file and everything else inside Corrade:
      • Also mention it in doc/corrade-singles.dox
      • And reference the single-header lib from the class documentation itself (look at e.g. Containers::Pointer for an example)
  7. Run magnum-singles/package/generate-loc.sh, update the README with its output (use block editing)
  8. If there's something important to be mentioned, update the changelog in the README
  9. Push to the next branch. If green, merge to master, if not, restart from point 1.

See Single-header generator tool for developer-facing description of the single-header generator tool.

Checklist for making a release

  1. Open a new 20XY.ac milestone
  2. Verify that there are no blocking issues in the current (20XY.ab) milestone, either fix them or move to the next milestone
  3. Verify that all CIs are green
  4. Go through doc/corrade-changelog.dox and update it, in case it doesn't contain all changes (use gitk to check when it was last updated)
  5. Go through fixed issues and merged PRs and add either a changelog mention added (and add a mention to the changelog), scrapped or no action needed label to wrap them up
  6. Go through merged PRs (and the most important issues) and add new people to doc/corrade-credits.dox and https://magnum.graphics/about/, if they are not there yet
  7. Update changelog for the next release:
    • change section names for the latest release from latest to 20XY-ab
    • change the title from Changes since 20XY.aa to 20XY.ab
    • add a paragraph stating date of release and referencing the to-be-added tag on GitHub
  8. Bump CORRADE_LIBRARY_VERSION and CORRADE_LIBRARY_SOVERSION in all projects, if needed — ensure consistency with Magnum releases
  9. Rebuild all projects with the new shared library version numbers, verify all tools and examples still behave properly
  10. Build and upload public docs (see Checklist for uploading documentation), verify that there are no new warnings and the changelog looks correct
  11. Push all new changes to a temporary branch (e.g., next)
  12. Wait for the CIs to get green
  13. Update conanfile.py with a new version — this has to be done before the version is tagged.
  14. Update Debian package changelog in package/debian/changelog, copypasting the last entry, updating it and using date -R for a date — again, this should be done before the version is tagged so stable releases in PPAs can be done directly from the tag with no extra patching
  15. Tag a new version using git tag -a v20XY.ab, say just Version 20XY.ab as a message
  16. Push the tag, verify that the CIs are still green
  17. Add content to the corresponding Magnum release announcement
  18. Update versions of ArchLinux AUR packages:
    • run makepkg in package/archlinux/corrade-git, verify it builds and says correct version, ideally with r0 at the ennd
    • copy the updated PKGBUILD to the AUR package repo, run makepkg --printsrcinfo > .SRCINFO there
    • commit the updated PKGBUILD and .SRCINFO, push
    • after pushing all, verify that the version is updated in the AUR web interface as well
  19. Update Homebrew package versions
  20. Ask someone to update the Ubuntu PPA
  21. Ask someone to update Vcpkg packages
  22. Close the 20XY.ab GitHub milestone
  23. Add link to the release notes to the tag on GitHub