Living Documentation

import this

class Agile_tour_speaker_should{
  @Test
  void share_screen_to_streamyard(){

    given_a_speaker_ready_to_speak();

    when_the_talk_has_started();

    then_Philippe_is_not_yelling_a_the_speaker();
  }
}

Feature: Agile Tour speaker

    Scenario: Share screen to streaming service

        Given A speaker ready to speak.
        When The talk has started
        Then Philippe is not yelling at the speaker

def sum(a, b):
    """
    Adds two numbers.

    >>> sum(2,2)
    5
    """
    return a + b


if __name__ == "__main__":
    import doctest

    doctest.testmod()

***********************************************************
File ".../python_doctest/sum.py", line 5, in __main__.sum
Failed example:
    sum(2,2)
Expected:
    5
Got:
    4
***********************************************************
1 items had failures:
   1 of   1 in __main__.sum
***Test Failed*** 1 failures.

defmodule Num do
    @moduledoc """
    Operations on numbers
    """
    @doc """
    Adds 2 numbers
    ## Examples
        iex> Num.sum(2, 2)
        5
    """
    def sum(a, b) do
        a + b
    end
end

mix test
Compiling 1 file (.ex)

  1) doctest Num.sum/2 (1) (NumTest)
     test/num_test.exs:3
     Doctest failed
     doctest:
       iex> Num.sum(2, 2)
       5
     code:  Num.sum(2, 2) === 5
     left:  4
     right: 5
     stacktrace:
       lib/num.ex:11: Num (module)

Finished in 0.02 seconds (0.00s async, 0.02s sync)
1 doctest, 1 failure

/// Adds two numbers together:
/// ```
/// # use documentation_test_rust::add;
/// let c = add(2, 2);
/// # assert_eq!(c, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
  return a + b;
}

   Doc-tests documentation_test_rust

running 1 test
test src/lib.rs - add (line 2) ... FAILED

failures:

---- src/lib.rs - add (line 2) stdout ----
Test executable failed (exit code 101).

stderr:
thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `4`,
 right: `5`', src/lib.rs:6:1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace



failures:
    src/lib.rs - add (line 2)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.18s

error: test failed, to rerun pass '--doc'

package num

func Sum(a int, b int) int {
	return a + b
}

package num

import "fmt"

func ExampleSum() {
	fmt.Println(Sum(2, 2))
	// Output: 5
}

--- FAIL: ExampleSum (0.00s)
got:
4
want:
5
FAIL
exit status 1
FAIL    doctest_golang  0.303s

package com.organisation.domain.order;
/**
 * A shopping cart blah blah blah.
 */
@Aggregate
public class ShoppingCart{
    // ...
}

package com.organisation.domain.order;
/**
 * An item that is hold the shopping cart to be ordered.
 */
@Entity
public class ShoppingCartItem{
    // ...
}

# Order

[Link](/src/main/java/com/organisation/domain/order/)

## Shopping Cart

A shopping cart blah blah blah.

[Link](/src/main/java/com/organisation/domain/order/ShoppingCart.java)

### Shopping Cart Item

An item that is hold the shopping cart to be ordered.

[Link](/src/main/java/com/organisation/domain/order/ShoppingCartItem.java)

                   +-------------+
                   | Asciidoctor |-------+
                   |   diagram   |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /---------------\
 |        | --+ Asciidoctor +--> |               |
 |  Text  |   +-------------+    |   Beautiful   |
 |Document|   |   !magic!   |    |    Output     |
 |     {d}|   |             |    |               |
 +---+----+   +-------------+    \---------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+

include:
  - template: "Security/SAST.gitlab-ci.yml"
  - template: "Security/Dependency-Scanning.gitlab-ci.yml"
  - template: "Security/Secret-Detection.gitlab-ci.yml"

{
    "$schema": "https://aka.ms/codetour-schema",
    "title": "Frontend basic tour",
    "steps": [
      {
        "file": "js/public/index.html",
        "description": "## Html entry point : `public/index.html`\n\nThis `public/index.html` is the first file that is loaded by the browser. \nIt loads the bundled VueJs application as a script.\nThe rendering of the application is then delegated to javascript.\n\nThe VueJs app is \"injected\" inside the `<div is=\"app\"></div>` element.\n\nThe bundled javascript script will be inserted in the `index.html` file in place of the comment : `<!-- built files will be auto injected -->`",
        "line": 19,
        "selection": {
          "start": {
            "line": 20,
            "character": 5
          },
          "end": {
            "line": 20,
            "character": 47
          }
        },
        "contents": "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\" />\n    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1.0\" />\n    <link rel=\"icon\" href=\"<%= BASE_URL %>favicon.ico\" />\n    <meta name=\"server-injected-data\" />\n  </head>\n\n  <body>\n    <noscript>\n      <strong\n        >We're sorry but <%= htmlWebpackPlugin.options.title %> doesn't work\n        properly without JavaScript enabled. Please enable it to\n        continue.</strong\n      >\n    </noscript>\n    <div id=\"app\"></div>\n    <!-- built files will be auto injected -->\n  </body>\n</html>\n"
      }
    ],
    "isPrimary": true,
    "description": "A quick overview of how browsing to the default URI translate to VueJs components and behaviours",
    "ref": "09cc5d1bd1ecd24e1e879b0392cf5830b2581c74"
  }

include::../examples/doctest/python_doctest/sum.py

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

docs: correct spelling of CHANGELOG

# Use Markdown Architectural Decision Records

- Status: accepted
- Date: 2020-09-24

## Context and Problem Statement

We want to record architectural decisions made in this project.
Which format and structure should these records follow?

## Considered Options

- [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch
- [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records
- [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
- [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
- Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
- Formless – No conventions for file format and structure

## Decision Outcome

Chosen option: "MADR 2.1.2 with Log4brains patch", because

- Implicit assumptions should be made explicit.
  Design documentation is important to enable people understanding the decisions later on.
  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
- The MADR format is lean and fits our development style.
- The MADR structure is comprehensible and facilitates usage & maintenance.
- The MADR project is vivid.
- Version 2.1.2 is the latest one available when starting to document ADRs.
- The Log4brains patch adds more features, like tags.

The "Log4brains patch" performs the following modifications to the original template:

- Change the ADR filenames format (`NNN-adr-name` becomes `YYYYMMDD-adr-name`), to avoid conflicts during Git merges.
- Add a `draft` status, to enable collaborative writing.
- Add a `Tags` field.

include:
  - template: "Verify/Accessibility.gitlab-ci.yml"
  - template: "Security/SAST.gitlab-ci.yml"
  - template: "Security/Dependency-Scanning.gitlab-ci.yml"
  - template: "Security/Secret-Detection.gitlab-ci.yml"

stages:
  - build
  - test
  - deploy
  - accessibility

build-baldir:
  stage: build
  script:
    - "echo do stuff"

deploy-baldir:
  needs:
    - "build-baldir"
  script:
    - "echo do stuff"

build-next:
  stage: build
  script:
    - "echo do stuff"

deploy-next:
  needs:
    - "build-next"
  script:
    - "echo do stuff"

build-audit:
  stage: accessibility
  script:
    - "echo do stuff"

deploy-audit:
  stage: accessibility
  script:
    - "echo do stuff"

# Installation steps

1. Connect to machine A with SSH
2. Move to directory `/www`
3. Delete content
4. Download latest artifact
5. extract artifact in `/www`
6. verify new site is online

# Installation steps

## Prepare

1. Connect to machine A with SSH

## Cleanup content

```shell
rm -rf /www/*
```

## Install latest version

```shell
wget https://where-your-artifact-is/artifact.tar.gz
tar -xvf artifact.tar.gz
# cleanup
rm -f artifact.tar.gz
```

# Installation steps

1. Connect to machine A with SSH
2. Run preinstalled script `./full-install.sh`
3. Run healthcheck script `./healthcheck.sh`