Contributing.md

Contributing to ApprovalTests.cpp

Contents

• Contributing - pairing and pull requests
  • Definition of Done
• Code of Conduct
• Formatting Code
• Coding Patterns
• Documentation
  • Future version numbers
  • Creating new pages
  • Internal links need to be absolute
  • Adding code and file samples
    • Managing CMake code samples
  • Checking the documentation
• Releases
• Running shell scripts in cygwin

Contributing - pairing and pull requests

The default way to add to most repositories is to fork and then create a pull-request.

This is NOT the default way to contribute to Approval Tests!

If you have something that you would like Approval Tests to have, including a bug you would like removed, we suggest you set up a pairing session (usually Skype or Facetime) with either Llewellyn or Clare or both.

A typical session lasts between 60 to 90 minutes. We do the work directly on master, on our own machines, with screen-sharing, and commit and push the results throughout the session. This results in quicker, higher-quality work. It gives us a better understanding of how people are using Approval Tests and the problems they encounter with it, and these sessions are also quite fun.

We use github's "co-author" feature, so everyone in the pairing session gets credit for the work. Virtually this entire project has been developed in this way, and is stronger for it.

We use Arlo's Commit Notation to prefix most commits, to indicate their level or risk.

Definition of Done

Note: Reminder for Clare and Llewellyn

• Tests
• Documentation
  • Sample code
  • Copy+pastable template (if appropriate)
  • A link on Features
  • A link on build/relnotes_x.y.z.md
  • Links on other appropriate places
• Check the Dashboard (after pushing)
• Retrospective (as an experiment) on what we learned from the work

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Formatting Code

If possible, please configure your editor to use this repository's .clang-format file.

Instructions for this are available:

• CLion:
  • Settings/Preferences | Editor | Code Style | Turn on "Enable ClangFormat with clangd server" checkbox.
  • More information: ClangFormat as Alternative Formatter

We have a CI job that checks for code not correctly formatted.

Coding Patterns

See Static variables for header-only releases.

Documentation

We welcome improvements to the documentation! Here's how we manage the documentation files.

Future version numbers

To refer to the next release, use 'v.x.y.z', and make sure that there is a step to edit the file to update that text to the actual version number in the release scripts.

Creating new pages

Note: All the master Markdown pages in this project are called mdsource/[something].source.md

Using the template page

If creating a new Markdown page, please make a copy of doc/mdsource/TemplatePage.source.md. This contains some boilerplate text which is tedious to create by hand.

The new file needs to be in a mdsource sub-directory.

Creating multiple pages

If creating multiple files, on Unix, you can use the script doc/mdsource/create_page.sh

cd doc/mdsource/
./create_page.sh TestingSingleObjects TestingContainers TestingCombinations

This won't overwrite existing files. It will write out the text to paste in to other .md files, to correctly link to the new file.

For documentation files outside of doc

If the new page will be outside of the doc folder, delete the following lines at the end:

---
   
[Back to User Guide](/doc/README.md#top)

Internal links need to be absolute

All references to other files in this project, such as hyperlinks and images, must specify the full path from the root of the repository. This will allow those links to work correctly in both the source and generated markdown files. Relative paths cannot work for both the source and the target file.

For example, use this:

* [this link will work everywhere](/doc/Reporters.md#top)

Not this:

* [this link is wrong](doc/Reporters.md#top)

And not this:

* [this link is wrong](Reporters.md#top)

Adding code and file samples

We use Simon Cropp's MarkdownSnippets tool to embed source code and other files in Markdown pages.

How it works:

• Call the source file [something].source.md.
• Make sure it is in a mdsource directory
• See the MarkdownSnippets documentation for how to:
  • annotate snippets of source code,
  • reference the snippets in documentation.
• Run run_markdown_templates.sh before commit, every time a .source.md file is updated
  • See run_markdown_templates.sh.
  • This will update the tables of contents and the machine-generated [something].md files.
  • If this does not work, see that script for how to install the tools it uses

Managing CMake code samples

The repository claremacrae/ApprovalTests.cpp.CMakeSamples has some sample CMake projects for various development scenarios.

I'm exploring ways of embedding some CMake files from that repo in to CMake Integration - see MarkdownSnippets #157.

For now, I've used claremacrae/ApprovalTests.cpp.CMakeSamples/create_markdown.py to convert the interesting CMake files to Markdown, and copy them to doc/mdsource/ with file names inc_*.include.md.

Checking the documentation

The script fix_markdown.sh can be used to do some checks of the Markdown documentation files.

Releases

• Everything for releases is in the build directory
• There's more information in How To Release

Running shell scripts in cygwin

To run .sh in cygwin on Windows, add these lines to ~/.bash_profile, and then re-start cygwin:

export SHELLOPTS
set -o igncr

Credit

---

Back to User Guide