Merge branch 'master' into douglas-35

.github/ISSUE_TEMPLATE/topic-proposal.md

@@ -3,7 +3,7 @@ name: Topic proposal
 about: Describes a topic that should be considered by SG20 for education guidelines
 title: "[TOPIC-REQUEST]"
 labels: Needs triaging
-assignees: BobSteagall, cjdb, jcvw
+assignees: vulder, jcvw
 
 ---
 

.github/workflows/ci.yml

@@ -3,7 +3,11 @@
 
 name: ci
 
-on: [push]
+on:
+  pull_request:
+  push:
+    branches:
+      master
 
 jobs:
   build:

.github/workflows/ci_tool_tests.yml

@@ -2,7 +2,8 @@
 
 name: Tool CI
 
-on: [push]
+on:
+  pull_request:
 
 jobs:
   build:

.github/workflows/release.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Collect git metadata
       id: git_metadata
       run: |
-        echo ::set-output name=VERSION::${GITHUB_REF#refs/tags/v}
+        echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
     # The following builds the document in multiple formats for deployment.
     - name: Build the document.
       shell: bash

config/spellcheck/ignored_words.txt

@@ -1,12 +1,19 @@
 args
+asm
+baz
 Bjarne
+bool
 checkmark
+coe
 constexpr
 cppreference
 Engelhart
+enum
 EPUB
 errno
 expr
+explorative
+extern
 Florian
 func
 Furst
@@ -16,8 +23,11 @@ Hyland
 JC
 Krathwohl
 ness
+nothrow
 NRVO
+RAII
 req
+Rethrowing
 RVO
 Sattler
 SG

config/spellcheck/wordlist

@@ -1,5 +1,6 @@
-personal_ws-1.1 en 18
 ABI
+API
+APIs
 boolean
 computable
 destructors
@@ -10,6 +11,7 @@ metaprogramming
 namespace
 namespaces
 ODR
+personal_ws-1.1 en 18
 preprocessor
 redeclarations
 SFINAE

sources/Makefile

@@ -115,7 +115,7 @@ knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat
 	$(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md
 
 contributors.md:
-	git log --all --pretty="%aN" | sort | uniq > contributors.md
+	git log --format="%aN%n%(trailers:key=Co-authored-by,valueonly=true)" | sed 's/ <.*>//g' | sort | uniq > contributors.md
 
 ################################################################################
 # Establish Pandoc settings.

sources/knowledge_areas.dat

@@ -12,7 +12,8 @@ P Preprocessor
 	? ? ? ? Macros
 B Basics Types, Objects, Values, Expressions, Statements, and Control-Flow Constructs
 	? ? ? ? Constant Objects
-	? ? ? ? Declarations and Definitions
+	? ? ? ? Declarations
+	def y y y Definitions
 	? ? ? ? Selection Constructs (e.g., if, ternary)
 	? ? ? ? Looping Constructs (e.g., for, while, etc.)
 F Functions
@@ -50,10 +51,10 @@ T Generic Programming (Templates)
 	? ? ? ? Requires Clauses
 	req-expr y y n Requires Expressions
 EH Error Handling
-	? ? ? ? Classes of Errors
+	coe y y n Categories of Errors
 	? ? ? ? errno
 	? ? ? ? Error Codes
-	? ? ? ? Exception Handling
+	eh y y y Exception Handling
 SL Standard Library
 	? ? ? ? Input/Output (I/O)
 	? ? ? ? Containers, Iterators, and Algorithms

sources/modules/compilation-model/buildsystems.md

@@ -0,0 +1,115 @@
+## Module name: Build systems
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      --- Knowledge about build systems
+
+Main              --- Usage of build system to compile a executable
+
+Advanced          --- Add external libraries as a dependencies  
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+* Building complex C++ projects by hand is tricky
+* Build systems can help to resolve dependencies
+* Build systems can help do distribute C++ code and help other to compile the code
+* Build systems can help to find and include libraries as dependencies
+* Build systems faciliate project management 
+* All major C++ projects are distributed with build systems 
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+Build systems are used to configure, build, and install complex C++ projects. 
+
+
+### Foundational: Knowledge about build systems
+
+#### Background/Required Knowledge
+
+A student: 
+* Should know how to compile and link C++ programs
+
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. To explain what a build system is
+2. To explain that a build systems resolves dependencies
+3. To explain that a build system supports compilation for different operating systems and architectures
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+None
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+* Mention that many build systems are available for C++ 
+* Mention benefits and challenges
+* Build system help to only compile the C++ files with code changes and not the complete project
+
+### Main: Usage of build system to compile a executable
+
+#### Background/Required Knowledge
+
+* All of the above.
+
+#### Student outcomes
+
+A student should be able to:
+
+1. Download a C++ package and build the package
+2. Write a configuration file to compile a C++ executable
+3. Pass compiler options via the build system
+4. Use the build system to generate the executable
+5. Write a configuration file to compile a library and link the library to a C++ executable
+
+#### Caveats
+
+The instructions are restricted to the chosen build system and
+not easily transferable.
+
+
+#### Points to cover
+
+* Include paths to header files to the configuration 
+* Adding compiler flags
+* How to build Release and Debug builds
+* Linking external libraries to the C++ project
+* Support compilation on different operating systems, compilers, and architectures 
+
+
+### Advanced
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+* How to build libraries 
+* How to have external libraries be downloaded during the build process
+* Mention that build systems provide support for unit testing
+

sources/modules/compilation-model/linkage.md

@@ -0,0 +1,6 @@
+## C++ compilation model: Linkage {#linkage}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/compilation-model/translation-units.md

@@ -0,0 +1,6 @@
+## C++ compilation model: Translation units {#translunits}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/error-handling/c-style-error-codes.md

@@ -0,0 +1,6 @@
+## Error handling: C-style error codes {#cerrcodes}
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+This topic is currently under construction and will soon be filled with information :)

sources/modules/error-handling/categories-of-errors.md

@@ -0,0 +1,114 @@
+## Error handling: Categories of errors
+
+_Skeleton descriptions are typeset in italic text,_
+_so please don't remove these descriptions when editing the topic._
+
+### Overview
+
+_Provides a short natural language abstract of the module’s contents._
+_Specifies the different levels of teaching._
+
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      Categories of errors
+
+Main              Handling different categories of errors
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
+
+_Why is this important?_
+_Why do we want to learn/teach this topic?_
+
+Programs can run in a normal state or erroneous state. Students should be able
+to identify different types of erroneous state and how to best handle them.
+
+### Topic introduction
+
+_Very brief introduction to the topic._
+
+This topic is an umbrella topic that refers to the different topics for types of errors and error handling.
+
+### Foundational: Categories of errors {#coe-found}
+
+#### Background/Required Knowledge
+
+A student:
+
+* should know the basics about linkage [[C++ compilation model: Linkage - Foundational]][1]
+
+#### Student outcomes
+
+_A list of things "a student should be able to" after the curriculum._
+_The next word should be an action word and testable in an exam._
+_Max 5 items._
+
+A student should be able to:
+
+1. Describe different kinds of errors and exceptional situations that require different approaches of error handling.
+2. Provide some examples of the different error categories.
+3. Identify potential erroneous code sections and attribute them to different error categories.
+
+
+#### Caveats
+
+_This section mentions subtle points to understand, like anything resulting in
+implementation-defined, unspecified, or undefined behavior._
+
+No caveats at present.
+
+#### Points to cover
+
+_This section lists important details for each point._
+
+Errors can happen at different times during software lifetime.
+
+* Compile-time errors
+* Link-time errors
+* Execution-time errors
+
+There are different types of errors
+
+* Logic errors (violations of logical preconditions)
+* Run-time errors (errors during code execution due to causes that are external to the program)
+
+
+### Main: Handling different categories of errors {#coe-main}
+
+#### Background/Required Knowledge
+
+#### Student outcomes
+
+A student should be able to:
+
+1. pick the right error handling approach for a given problem.
+2. enumerate different error handling strategies.
+3. make a clear distinction between error-handling code and normal-case handling code
+
+
+#### Caveats
+
+* The different error handling strategies have different trade-offs (runtime performance, readability, ...)
+* The trade-off space depends on the run-time context (embedded, ...)
+* There also exist unhandleable errors (e.g., ODR violations, undefined behavior)
+
+#### Points to cover
+
+* Exception handling [[Error handling: Exception handling - Foundational]][2]
+* Returning a value indication failure [[Error handling: C-style error-codes - Foundational]][3]
+* Terminating the program
+* Improving error handling by having the error occur at an earlier stage in the software development cycle [[Error handling: Static assert - Foundational]][4]
+
+### Advanced {#coe-advanced}
+
+_These are important topics that are not expected to be covered but provide
+guidance where one can continue to investigate this topic in more depth._
+
+[1]: ../compilation-model/linkage.md
+[2]: ../error-handling/exception-handling.md
+[3]: ../error-handling/c-style-error-codes.md
+[4]: ../error-handling/static-assert.md