diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..b69d2c6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# exclude .gitignore, CI config and similar from the generated tarball +.git* export-ignore diff --git a/.github/workflows/build_main.yml b/.github/workflows/build_main.yml new file mode 100644 index 0000000..42d2277 --- /dev/null +++ b/.github/workflows/build_main.yml @@ -0,0 +1,80 @@ +# This is a basic workflow to help you get started with Actions + +name: CI - Releases and Main + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the main branch +on: + push: + branches: [ main ] + tags: + - "[2-9][0-9][0-9][0-9].[0-9]+-rev[0-9]+" + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout Source + uses: actions/checkout@v3 + with: + submodules: recursive + - name: Verify Gradle Wrapper + uses: gradle/wrapper-validation-action@v1 + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: 17 + + # If we're building a release, we need to set the variable RELEASE_VERSION + - name: Set Environment Variables for Release Version + if: startsWith(github.ref, 'refs/tags/') + run: echo "RELEASE_VERSION=${GITHUB_REF:10}" >> $GITHUB_ENV + + - name: Execute Gradle Build + uses: gradle/gradle-build-action@v2 + env: + CI: true + with: + gradle-version: wrapper + arguments: buildDocs + + # release and deploy only if we're building a release + - name: Prepare Deployment + if: startsWith(github.ref, 'refs/tags/') + run: | + rm -rf ./build/tmp + cp ./docs-ext/curriculum-*.pdf ./build 2>/dev/null || : + zip -r release.zip ./build + mkdir release_dir + cp ./build/curriculum-*.pdf ./release_dir 2>/dev/null || : + mv release.zip ./release_dir/release-${{ env.RELEASE_VERSION }}.zip + - name: Create New Release + if: startsWith(github.ref, 'refs/tags/') + id: create-release + uses: ncipollo/release-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token + with: + tag: ${{ env.RELEASE_VERSION }} + name: Release ${{ env.RELEASE_VERSION }} + draft: false + prerelease: false + bodyFile: "CHANGELOG.md" + artifacts: "license-copyright/LICENSE.adoc,release_dir/*.pdf,release_dir/*.zip" + token: ${{ secrets.GITHUB_TOKEN }} + - name: Deploy + if: startsWith(github.ref, 'refs/tags/') + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + commit_message: Publish Release ${{ env.RELEASE_VERSION }} diff --git a/.github/workflows/build_pr.yml b/.github/workflows/build_pr.yml new file mode 100644 index 0000000..a1d0aa0 --- /dev/null +++ b/.github/workflows/build_pr.yml @@ -0,0 +1,43 @@ +# This is a basic workflow to help you get started with Actions + +name: CI – Pull Requests + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the main branch +on: + pull_request: + branches: [ main ] +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: checkout source + uses: actions/checkout@v3 + with: + submodules: recursive + - name: Verify Gradle Wrapper + uses: gradle/wrapper-validation-action@v1 + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: 17 + - name: Execute Gradle Build + uses: gradle/gradle-build-action@v2 + with: + gradle-version: wrapper + arguments: buildDocs + - name: Upload Build Artifacts + uses: actions/upload-artifact@v3 + with: + name: curriculum files (PDF and HTML) + path: | + build/*.pdf + build/*.html + retention-days: 10 diff --git a/.github/workflows/build_releasecandidate.yml b/.github/workflows/build_releasecandidate.yml new file mode 100644 index 0000000..005b42d --- /dev/null +++ b/.github/workflows/build_releasecandidate.yml @@ -0,0 +1,85 @@ +# This is a basic workflow to help you get started with Actions + +name: CI – Release Candidate + +# Controls when the action will run. Triggers the workflow on push events if the pushed +# tag is a release candidate +on: + push: + tags: + - "[2-9][0-9][0-9][0-9].[0-9]+-RC[0-9]+" + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout Source + uses: actions/checkout@v3 + with: + submodules: recursive + - name: Update index.adoc + run: | + rm docs/index.adoc + mv docs/index_rc.adoc docs/index.adoc + - name: Verify Gradle Wrapper + uses: gradle/wrapper-validation-action@v1 + - name: Set up JDK 17 + uses: actions/setup-java@v3 + with: + distribution: 'temurin' + java-version: 17 + + # If we're building a release, we need to set the variable RELEASE_VERSION + - name: Set Environment Variables for Release Version + if: startsWith(github.ref, 'refs/tags/') + run: echo "RELEASE_VERSION=${GITHUB_REF:10}" >> $GITHUB_ENV + + - name: Execute Gradle Build + uses: gradle/gradle-build-action@v2 + env: + CI: true + with: + gradle-version: wrapper + arguments: buildDocs + + # do the following two things only for a release! + - name: Prepare Deployment + if: startsWith(github.ref, 'refs/tags/') + run: | + rm -rf ./build/tmp + cp ./docs-ext/curriculum-*.pdf ./build 2>/dev/null || : + zip -r release.zip ./build + mkdir release_dir + cp ./build/curriculum-*.pdf ./release_dir 2>/dev/null || : + mv release.zip ./release_dir/release-${{ env.RELEASE_VERSION }}.zip + - name: Create New Release Candidate + if: startsWith(github.ref, 'refs/tags/') + id: create-release-candidate + uses: ncipollo/release-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token + with: + tag: ${{ env.RELEASE_VERSION }} + name: Release Candidate ${{ env.RELEASE_VERSION }} + draft: false + prerelease: true + bodyFile: "CHANGELOG.md" + artifacts: "license-copyright/LICENSE.adoc,release_dir/*.pdf,release_dir/*.zip" + token: ${{ secrets.GITHUB_TOKEN }} + - name: Deploy Release Candidate to GitHub Pages + if: startsWith(github.ref, 'refs/tags/') + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build + destination_dir: release-candidate + keep_files: true + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + commit_message: Publish Release Candidate ${{ env.RELEASE_VERSION }} diff --git a/.github/workflows/update_pr_with_comment.yml b/.github/workflows/update_pr_with_comment.yml new file mode 100644 index 0000000..172c879 --- /dev/null +++ b/.github/workflows/update_pr_with_comment.yml @@ -0,0 +1,71 @@ +name: Comment on Pull Request + +on: + workflow_run: + types: [completed] + workflows: [CI – Pull Requests] + +jobs: + comment: + if: ${{ github.event.workflow_run.conclusion == 'success' }} && ${{github.event_name == 'pull_request' }} + runs-on: ubuntu-latest + steps: + - name: Get Artifact and Pull request info + env: + GITHUB_TOKEN: ${{ github.token }} + WORKFLOW_RUN_EVENT_OBJ: ${{ toJSON(github.event.workflow_run) }} + OWNER: ${{ github.repository_owner }} + REPO: ${{ github.event.repository.name }} + run: | + PREVIOUS_JOB_ID=$(jq -r '.id' <<< "$WORKFLOW_RUN_EVENT_OBJ") + echo "Previous Job ID: $PREVIOUS_JOB_ID" + echo "PREVIOUS_JOB_ID=$PREVIOUS_JOB_ID" >> "$GITHUB_ENV" + + SUITE_ID=$(jq -r '.check_suite_id' <<< "$WORKFLOW_RUN_EVENT_OBJ") + echo "Previous Suite ID: $SUITE_ID" + echo "SUITE_ID=$SUITE_ID" >> "$GITHUB_ENV" + + ARTIFACT_ID=$(gh api "/repos/$OWNER/$REPO/actions/artifacts" \ + --jq ".artifacts.[] | + select(.workflow_run.id==${PREVIOUS_JOB_ID}) | + select(.expired==false) | + .id") + + echo "Artifact ID: $ARTIFACT_ID" + echo "ARTIFACT_ID=$ARTIFACT_ID" >> "$GITHUB_ENV" + + PR_NUMBER=$(jq -r '.pull_requests[0].number' \ + <<< "$WORKFLOW_RUN_EVENT_OBJ") + + echo "Pull request Number: $PR_NUMBER" + echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_ENV" + + HEAD_SHA=$(jq -r '.pull_requests[0].head.sha' \ + <<< "$WORKFLOW_RUN_EVENT_OBJ") + + echo "Head SHA: $HEAD_SHA" + echo "HEAD_SHA=$HEAD_SHA" >> "$GITHUB_ENV" + - name: Find Comment + uses: peter-evans/find-comment@v2 + id: find-comment + with: + issue-number: ${{ env.PR_NUMBER }} + comment-author: 'github-actions[bot]' + - name: Update Comment + env: + JOB_PATH: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ env.PREVIOUS_JOB_ID }}" + ARTIFACT_URL: "${{ github.server_url }}/${{ github.repository }}/suites/${{ env.SUITE_ID }}/artifacts/${{ env.ARTIFACT_ID }}" + HEAD_SHA: "${{ env.HEAD_SHA }}" + uses: peter-evans/create-or-update-comment@v3 + with: + issue-number: ${{ env.PR_NUMBER }} + comment-id: ${{ steps.find-comment.outputs.comment-id }} + edit-mode: replace + body: |- + Build Successful! You can find a link to the downloadable artifacts below. + + | Name | Link | + | -------- | ----------------------- | + | Commit | ${{ env.HEAD_SHA }} | + | Logs | ${{ env.JOB_PATH }} | + | Download | ${{ env.ARTIFACT_URL }} | diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bb904ca --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.DS_Store + +.gradle +build +.idea +advanced-template.iml +.settings/org.eclipse.buildship.core.prefs +.project +learning-objectives.adoc diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..f80c461 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,9 @@ +[submodule "pdf-theme"] + path = pdf-theme + url = https://github.com/isaqb-org/pdf-theme +[submodule "html-theme"] + path = html-theme + url = https://github.com/isaqb-org/html-theme +[submodule "license-copyright"] + path = license-copyright + url = https://github.com/isaqb-org/license-copyright diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..24da3ac --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,16 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "gradle", + "type": "shell", + "command": "gradle", + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c74bc43 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Release Notes +## New in 2020.7 +- Remove lots of old/unused stuff regarding remarks +- Use Gradle Wrapper in GitHub Actions +- Take document version from git tag + +## New in 2020.6 + +- CHANGELOG can be created from file +- Use new and simplified release action +- Update to latest Aciidoctor versions +- Update to latest Gradle (7.5.1) diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..8823dcc --- /dev/null +++ b/README.adoc @@ -0,0 +1,187 @@ += Template for https://isaqb.org[iSAQB] Advanced Level Curricula + +:toc: +:toc-placement!: + +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +endif::[] + +== Status +image:https://github.com/isaqb-org/advanced-template/workflows/CI%20-%20Releases%20and%20Main/badge.svg?branch=main["CI – Releases and Main"] +image:https://img.shields.io/github/last-commit/isaqb-org/advanced-template/main.svg["Last commit"] +image:https://img.shields.io/github/contributors/isaqb-org/advanced-template.svg["Contributors",link="https://github.com/isaqb-org/advanced-template/graphs/contributors"] +image:https://img.shields.io/github/issues/isaqb-org/advanced-template.svg["Issues",link="https://github.com/isaqb-org/advanced-template/issues"] +image:https://img.shields.io/github/issues-closed/isaqb-org/advanced-template.svg["Issues closed",link="https://github.com/isaqb-org/advanced-template/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"] + + +This is <>. + +== Content +This repository contains a template for iSAQB Advanced Level *curricula* in AsciiDoc. + +toc::[] + +== How to contribute or participate +Create an issue, a merge- or pull-request + +== How to use this template + +. Either click on "Use this template" in the Github UI or Clone the repository - including the submodule: ++ +-- +[source,shell] +---- +Via SSH: +git clone git@github.com:isaqb-org/advanced-template.git --recursive + +Via HTTPS: +git clone https://github.com/isaqb-org/advanced-template.git --recursive +---- +-- +. Rename the repository to the name of your curriculum e.g. `curriculum-flex` +. Rename the file `/docs/advanced-template.adoc` to the name of your curriculum e.g. `curriculum-flex.adoc` (this is later on referred to as `curriculumFileName`) +. Open the file `./config/setup.adoc` to adjust configuration specific to your curriculum: +.. `:curriculum-short: MODULKUERZEL`: this is the abbreviation of your module. Replace MODULKUERZEL with your module name e.g. FLEX +.. `:curriculum-name: MODULNAME IN VOLLER LAENGE`: the full German title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices und Self-Contained Systems" +.. `:curriculum-name: MODULNAME IN VOLLER LAENGE`: the full English title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices and Self-Contained Systems" +. Open the file `build.gradle` to adjust attributes specific to your curriculum: +[loweralpha] +.. `curriculumFileName`: the name of the asciidoc root file of your curriculum e.g. `curriculum-flex` (see above! The `.adoc` suffix is added automatically, omit it here!) +. Open README.adoc and replace the string `curriculum-template` with the name of your Github repository e.g. `curriculum-flex` +. Build the project with http://www.gradle.com[gradle] (you need a locally installed JDK 17 or higher) via `./gradlew`. +. Once the "BUILD SUCCESSFUL" is show, you can review the build result under `./build/index.html` + +== How to write iSAQB Advanced Level Curricula with AsciiDoc + +=== Requirements and (our) solutions + +[cols="1,2a",options="header"] +|=== +|Requirement +|Solution + +|Visually appealing pdf output +|We created an iSAQB pdf theme, located under the `/style` directory. The original is maintained in the `adoc2pdf` repository. + +|Multiple people contribute content, review and comment +|highly modularized content: Small chunks, like learning-goals or subsections, are contained in their own asciidoc-files. + +|Multiple languages, at least EN and DE (i18n) +|Every piece of text is enclosed in _tags_ like `tag::EN[]`. The build process collects all parts for the desired language. + +|Simple conversion from asciidoc to pdf (and html) +|There is currently one option available: + +* Gradle based build, requiring a local Java runtime. +|=== + +- - - + +**TODO:** Add explanation for keywords and general procedure when creating a new Advanced Level Curriculum. + +- - - + +=== How to organize files? + +==== Prerequisite: AsciiDoc include +You should know some details about the AsciiDoc include statement. + +If the Asciidoctor processor encounters a statement like the one below: + +[source,asciidoc] +---- + include::directory/file.adoc[] +---- + +It will replace this include statement with the contents of `file.adoc`. That's easy and straightforward. + +=== Content and Structure files +As we are writing i18n we need to strictly distiguish between two +kind of files: + +* *content* files, they contain text, tables or diagrams that shall be included in the output. +* *structure* files, containing only include-statements, configuration information. Structure files include both content-files and other structure files. + +For content files, specific parts will be included via the tag-syntax described above. +For that purpose we define a variable named `include_configuration` in the file `config/setup.adoc`. + +==== Structure File Example + +In theory, you can just use the `docs/curriculum-template.adoc` as is and just +edit the section documents in the subdirectories. If you want to create your own file, +we recommend to stick with the following: + +From `docs/curriculum-template.adoc` (excerpts): + +[source,asciidoc] +---- += Template Curriculum: CPSA Certified Professional for Software Architecture^(R)^ +:doctype: book + +include::config/setup.adoc[] // // <1> + +:document-version: 2020.2 // //<2> + +:sectnums!: // // <3> +include::00-preamble/copyright.adoc[{include_configuration}] // // <4> + +<<< // // <5> +:toc: + +<<< +:sectnums!: +include::00-preamble/00-introduction.adoc[] // //<6> + +---- + +1. We propose to put the asciidoc configuration in this special file (`docs/config/setup.adoc`). +2. You can set a version, but it may be overridden in the build process. +3. You can turn section numbering on and off (here: off). +4. This includes parts of the `docs/00-preamble/copyright.adoc` file. +5. The `<<<` will create a pagebreak in pdf files. +6. Include the whole file 00-introduction.adoc. + + +=== Suggestions + +TBD. + +== How to build the documents + +Prerequisite: You need a Java Runtime(tm) installed. + +You build the output documents with gradle. +That will produce both pdf and html output in German (DE) _and_ English (EN), unless you modify the configuration. + +In case you want to change that, adjust the following part of `build.gradle`: + +[source,groovy] +---- +task buildDocs { + group 'Documentation' + description 'Grouping task for generating all languages in several formats' + dependsOn "renderDE", "renderEN" +} +---- + +In the task "renderDE", certain attributes (aka variables) are defined that configure the corresponding output. + +== Additional translations/languages +include::docs-ext/EXTERNAL_DOCUMENTS_README.adoc[] + +== Maintainers + +This repository is currently maintained by Benjamin Wolf. +It was forked from https://github.com/isaqb-org/curriculum-template, +so the contributors of that project basically contributed to this one, too. + + +[[copyrighted]] +== Licensing and Copyright + +include::license-copyright/LICENSE.adoc[] diff --git a/build.gradle b/build.gradle new file mode 100644 index 0000000..9764091 --- /dev/null +++ b/build.gradle @@ -0,0 +1,44 @@ +import java.text.SimpleDateFormat + +plugins { + id "java" + id "application" +} + +def group = "org.isaqb" +def releaseVersion = System.getenv("RELEASE_VERSION") +def localVersion = "LocalBuild" +project.version = releaseVersion == null ? localVersion : releaseVersion +def curriculumFileName = "curriculum-template" +def versionDate = new SimpleDateFormat("yyyyMMdd").format(new Date()) +def languages = ["DE", "EN"] + +repositories { + mavenCentral() +} + +dependencies { + implementation("org.asciidoctor:asciidoctorj:2.5.10") + implementation("org.asciidoctor:asciidoctorj-pdf:2.3.9") +} + +application { + mainClass.set("org.isaqb.asciidoc.Main") + applicationDefaultJvmArgs = [ + """-DprojectVersion=${project.version}""", + """-DcurriculumFileName=${curriculumFileName}""", + """-DversionDate=${versionDate}""", + """-Dlanguages=${languages.join(',')}""", + """--add-opens""", """java.base/sun.nio.ch=ALL-UNNAMED""", + """--add-opens""", """java.base/java.io=ALL-UNNAMED"""] +} + +apply from: 'scripts/includeLearningObjectives.gradle' + +tasks.register('buildDocs') { + description = 'Grouping task for generating all languages in several formats' + group = 'documentation' + dependsOn "includeLearningObjectives", "run" +} + +defaultTasks "buildDocs" diff --git a/docs-ext/EXTERNAL_DOCUMENTS_README.adoc b/docs-ext/EXTERNAL_DOCUMENTS_README.adoc new file mode 100644 index 0000000..0d32bfc --- /dev/null +++ b/docs-ext/EXTERNAL_DOCUMENTS_README.adoc @@ -0,0 +1,13 @@ +Copy translated versions (PDF) of the curriculum (other than German or English) to the directory `docs-ext`. + +Please make sure, that the file name is well-formed and complies with the following format: + +`curriculum-xxxx-lc.pdf` + +`xxxx`: insert the name of the curriculum, e.g. `web` or `flex` + +`lc`: iso language code of the translation, e.g. `es` (Spanish) or `pt` (Portuguese) + +Example: `curriculum-web-es.pdf` <- Spanish version of the WEB curriculum. + +**ATTENTION:** For every document that you add to `docs-ext`, you also have to create an entry in `index.adoc` +so that people can access it from the overview page of this curriculum. diff --git a/docs-ext/curriculum-template-es.pdf b/docs-ext/curriculum-template-es.pdf new file mode 100644 index 0000000..a1c6b93 Binary files /dev/null and b/docs-ext/curriculum-template-es.pdf differ diff --git a/docs/00a-preamble/00-introduction.adoc b/docs/00a-preamble/00-introduction.adoc new file mode 100644 index 0000000..d5a7d72 --- /dev/null +++ b/docs/00a-preamble/00-introduction.adoc @@ -0,0 +1,13 @@ +// tag::DE[] +== Einführung: Allgemeines zum iSAQB Advanced Level +// end::DE[] + +// tag::EN[] +== Introduction: General information about the iSAQB Advanced Level +// end::EN[] + +include::01-what-to-expect-of-an-advanced-level-module.adoc[{include_configuration}] + +include::02-advanced-level-knowledge.adoc[{include_configuration}] + +include::03-prerequisites.adoc[{include_configuration}] diff --git a/docs/00a-preamble/01-what-to-expect-of-an-advanced-level-module.adoc b/docs/00a-preamble/01-what-to-expect-of-an-advanced-level-module.adoc new file mode 100644 index 0000000..f2c2328 --- /dev/null +++ b/docs/00a-preamble/01-what-to-expect-of-an-advanced-level-module.adoc @@ -0,0 +1,15 @@ +// tag::DE[] +=== Was vermittelt ein Advanced Level Modul? + +Das Modul kann unabhängig von einer CPSA-F-Zertifizierung besucht werden. + +- Der iSAQB Advanced Level bietet eine modulare Ausbildung in drei Kompetenzbereichen mit flexibel gestaltbaren Ausbildungswegen. Er berücksichtigt individuelle Neigungen und Schwerpunkte. +- Die Zertifizierung erfolgt als Hausarbeit. Die Bewertung und mündliche Prüfung wird durch vom iSAQB benannte Expert:innen vorgenommen. +// end::DE[] + +// tag::EN[] +=== What is taught in an Advanced Level module? +- The iSAQB Advanced Level offers modular training in three areas of competence with flexibly designable training paths. It takes individual inclinations and priorities into account. +- The certification is done as an assignment. The assessment and oral exam is conducted by experts appointed by the iSAQB. +// end::EN[] + diff --git a/docs/00a-preamble/02-advanced-level-knowledge.adoc b/docs/00a-preamble/02-advanced-level-knowledge.adoc new file mode 100644 index 0000000..9d5683e --- /dev/null +++ b/docs/00a-preamble/02-advanced-level-knowledge.adoc @@ -0,0 +1,21 @@ +// tag::DE[] +=== Was können Absolventen des Advanced Level (CPSA-A)? +CPSA-A-Absolventen können: + +- eigenständig und methodisch fundiert mittlere bis große IT-Systeme entwerfen +- in IT-Systemen mittlerer bis hoher Kritikalität technische und inhaltliche Verantwortung übernehmen +- Maßnahmen zur Erreichung von Qualitätsanforderungen konzeptionieren, entwerfen und dokumentieren sowie Entwicklungsteams bei der Umsetzung dieser Maßnahmen begleiten +- architekturrelevante Kommunikation in mittleren bis großen Entwicklungsteams steuern und durchführen + +// end::DE[] + +// tag::EN[] +=== What can Advanced Level (CPSA-A) graduates do? +CPSA-A graduates can: + +- Independently and methodically design medium to large IT systems +- In IT systems of medium to high criticality, assume technical and content-related responsibility +- Conceptualize, design, and document actions to achieve quality requirements and support development teams in the implementation of these actions +- Control and execute architecture-relevant communication in medium to large development teams +// end::EN[] + diff --git a/docs/00a-preamble/03-prerequisites.adoc b/docs/00a-preamble/03-prerequisites.adoc new file mode 100644 index 0000000..adc00b6 --- /dev/null +++ b/docs/00a-preamble/03-prerequisites.adoc @@ -0,0 +1,25 @@ +// tag::DE[] +=== Voraussetzungen zur CPSA-A-Zertifizierung +* erfolgreiche Ausbildung und Zertifizierung zum Certified Professional for Software Architecture, Foundation Level^(R)^ (CPSA-F) +* mindestens drei Jahre Vollzeit-Berufserfahrung in der IT-Branche; dabei Mitarbeit an Entwurf und Entwicklung von mindestens zwei unterschiedlichen IT-Systemen +** Ausnahmen sind auf Antrag zulässig (etwa: Mitarbeit in Open-Source-Projekten) +* Aus- und Weiterbildung im Rahmen von iSAQB-Advanced-Level-Schulungen im Umfang von mindestens 70 Credit Points aus mindestens drei unterschiedlichen Kompetenzbereichen +* erfolgreiche Bearbeitung der CPSA-A-Zertifizierungsprüfung + +// end::DE[] + +// tag::EN[] +=== Requirements for CPSA-A certification +* Successful training and certification as a Certified Professional for Software Architecture, Foundation Level^(R)^ (CPSA-F) +* At least three years of full-time professional experience in the IT sector; collaboration on the design and development of at least two different IT systems +** Exceptions are allowed on application (e.g., collaboration on open source projects) +* Training and further education within the scope of iSAQB Advanced Level training courses with a minimum of 70 credit points from at least three different areas of competence +* Successful completion of the CPSA-A certification exam +// end::EN[] + +{empty} + +{empty} + + +[.text-center] +image:00-preamble/cpsa-a-logo.png[pdfwidth=50%,align=center,alt="Certified Professional for Software Architecture^(R)^ Advanced Level (CPSA-A)"] + diff --git a/docs/00b-basics/00-basics.adoc b/docs/00b-basics/00-basics.adoc new file mode 100644 index 0000000..79711f3 --- /dev/null +++ b/docs/00b-basics/00-basics.adoc @@ -0,0 +1,17 @@ +// header file for curriculum section 1: Basic Concepts +// (c) iSAQB e.V. (https://isaqb.org) +// ==================================================== + +== {basics} + +include::01-what-to-expect-of-this-module.adoc[{include_configuration}] + +include::02-curriculum-structure-and-chronological-breakdown.adoc[{include_configuration}] + +include::03-timing-didactics-and-more.adoc[{include_configuration}] + +include::04-prerequisites-for-this-training.adoc[{include_configuration}] + +include::05-curriculum-outline.adoc[{include_configuration}] + +include::06-complementary-information.adoc[{include_configuration}] diff --git a/docs/00b-basics/01-what-to-expect-of-this-module.adoc b/docs/00b-basics/01-what-to-expect-of-this-module.adoc new file mode 100644 index 0000000..a888ecb --- /dev/null +++ b/docs/00b-basics/01-what-to-expect-of-this-module.adoc @@ -0,0 +1,20 @@ +// tag::DE[] +=== Was vermittelt das Modul „{curriculum-short}“? + +Das Modul präsentiert den Teilnehmerinnen und Teilnehmern {curriculum-name} als … +Am Ende des Moduls kennen die Teilnehmerinnen und Teilnehmer … und können … +// end::DE[] + +// tag::EN[] +=== What does the module “{curriculum-short}” convey? + +The module presents {curriculum-short} to the participants … +At the end of the module, the participants know … and are able to … +// end::EN[] + + +[NOTE] +==== +Hier bitte das Modul bzw. dessen Lerninhalte zusammenfassend in 5-8 Sätzen beschreiben. Dabei `{curriculum-name}` +nicht entfernen, beim Zusammenbauen wird dieser Platzhalter mit dem Modulnamen ersetzt. +==== diff --git a/docs/00b-basics/02-curriculum-structure-and-chronological-breakdown.adoc b/docs/00b-basics/02-curriculum-structure-and-chronological-breakdown.adoc new file mode 100644 index 0000000..0e8e7f5 --- /dev/null +++ b/docs/00b-basics/02-curriculum-structure-and-chronological-breakdown.adoc @@ -0,0 +1,47 @@ +// tag::DE[] +=== Struktur des Lehrplans und empfohlene zeitliche Aufteilung + +[cols="<,>", options="header"] +|=== +| Inhalt | Empfohlene Mindestdauer (min) +| 1. Thema mit Einleitung | 180 +| 2. Thema über xz | 150 +| 3. Thema mit viel Theorie | 120 +| 4. Thema mit xy und Beispiel | 180 +| 5. Thema mit abc und d | 210 +| 6. Thema mit Abschlussbeispiel | 120 +| | +| Summe | 960 (16h) + +|=== + +// end::DE[] + +// tag::EN[] +=== Curriculum Structure and Recommended Durations + +[cols="<,>", options="header"] +|=== +| Content +| Recommended minimum duration (minutes) +| 1. Introduction | 180 +| 2. xz | 150 +| 3. Lots of theory | 120 +| 4. xy and example | 180 +| 5. abc und d | 210 +| 6. Final example | 120 +| | +| Total | 960 (16h) + +|=== + +// end::EN[] + +[NOTE] +==== +Bitte die oben angegebene Tabelle entsprechend anpassen. + += = = + +Please adjust the table above according to your curriculum. +==== diff --git a/docs/00b-basics/03-timing-didactics-and-more.adoc b/docs/00b-basics/03-timing-didactics-and-more.adoc new file mode 100644 index 0000000..16b3da5 --- /dev/null +++ b/docs/00b-basics/03-timing-didactics-and-more.adoc @@ -0,0 +1,49 @@ + +[NOTE] +==== +Bitte in dieser Datei nur die "**?**"-Platzhalter durch die Anzahl der Tage sowie die erreichbaren Punkte ersetzen. Ansonsten keine Änderungen vornehmen! +==== + + +:recommended-duration-in-days: **?** +:methodical-credits: **?** +:technical-credits: **?** +:communicative-credits: **?** + +// tag::DE[] +=== Dauer, Didaktik und weitere Details + +Die unten genannten Zeiten sind Empfehlungen. Die Dauer einer Schulung zum Modul {curriculum-short} +sollte mindestens {recommended-duration-in-days} Tage betragen, kann aber länger sein. +Anbieter können sich durch Dauer, Didaktik, Art und Aufbau der Übungen sowie der detaillierten Kursgliederung voneinander unterscheiden. +Insbesondere die Art der Beispiele und Übungen lässt der Lehrplan komplett offen. + +Lizenzierte Schulungen zu {curriculum-short} tragen zur Zulassung zur abschließenden Advanced-Level-Zertifizierungsprüfung folgende Credit Points) bei: + +[stripes=none, frame=none, grid=rows] +|=== +| Methodische Kompetenz: | {methodical-credits} Punkte +| Technische Kompetenz: | {technical-credits} Punkte +| Kommunikative Kompetenz: | {communicative-credits} Punkte +|=== + +// end::DE[] + +// tag::EN[] +=== Duration, Teaching Method and Further Details + +The times stated below are recommendations. +The duration of a training course on the {curriculum-short} module should be at least {recommended-duration-in-days} days, but may be longer. +Providers may differ in terms of duration, teaching method, type and structure of the exercises, and the detailed course structure. +In particular, the curriculum provides no specifications on the nature of the examples and exercises. + +Licensed training courses for the {curriculum-short} module contribute the following credit points towards admission to the final Advanced Level certification exam: + +[stripes=none, frame=none, grid=rows] +|=== +| Methodical Competence: | {methodical-credits} Points +| Technical Competence: | {technical-credits} Points +| Communicative Competence: | {communicative-credits} Points +|=== + +// end::EN[] diff --git a/docs/00b-basics/04-prerequisites-for-this-training.adoc b/docs/00b-basics/04-prerequisites-for-this-training.adoc new file mode 100644 index 0000000..1cc4670 --- /dev/null +++ b/docs/00b-basics/04-prerequisites-for-this-training.adoc @@ -0,0 +1,40 @@ +// tag::DE[] +=== Voraussetzungen + +Teilnehmerinnen und Teilnehmer **sollten** folgende Kenntnisse und/oder Erfahrung mitbringen: + +- Voraussetzung 1 +- Voraussetzung 2, etc. + +**Hilfreich** für das Verständnis einiger Konzepte sind darüber hinaus: + +- Kenntnisgruppe 1: + * Kenntnis 1 + * Erfahrung 2 + * Kenntnis 3 + * Erfahrung 4 + * Wissen 5 +// end::DE[] + +// tag::EN[] +=== Prerequisites + +Participants **should** have the following prerequisite knowledge: + +- Prerequisite 1 +- Prerequisite 2, etc. + +Knowledge in the following areas may be **helpful** for understanding some concepts: + +- Area 1: + * Knowledge 1 + * Experience 2 + * Knowledge 3 + * Experience 4 + * Understanding 5 +// end::EN[] + +[NOTE] +==== +Kenntnisgruppen sowie Voraussetzungen bitte entsprechend ausformulieren! +==== diff --git a/docs/00b-basics/05-curriculum-outline.adoc b/docs/00b-basics/05-curriculum-outline.adoc new file mode 100644 index 0000000..6c2f04e --- /dev/null +++ b/docs/00b-basics/05-curriculum-outline.adoc @@ -0,0 +1,24 @@ +// tag::DE[] +=== Gliederung des Lehrplans + +Die einzelnen Abschnitte des Lehrplans sind gemäß folgender Gliederung beschrieben: + +- **Begriffe/Konzepte**: Wesentliche Kernbegriffe dieses Themas. +- **Unterrichts-/Übungszeit**: Legt die Unterrichts- und Übungszeit fest, die für dieses Thema bzw. dessen Übung in einer akkreditierten Schulung mindestens aufgewendet werden muss. +- **Lernziele**: Beschreibt die zu vermittelnden Inhalte inklusive ihrer Kernbegriffe und -konzepte. + +Dieser Abschnitt skizziert damit auch die zu erwerbenden Kenntnisse in entsprechenden Schulungen. +// end::DE[] + +// tag::EN[] +=== Structure of the Curriculum + +The individual sections of the curriculum are described according to the following structure: + +- **Terms/principles**: Essential core terms of this topic. +- **Teaching/practice time**: Defines the minimum amount of teaching and practice time that must be spent on this topic or its practice in an accredited training course. +- **Learning goals**: Describes the content to be conveyed including its core terms and principles. + +This section therefore also outlines the skills to be acquired in corresponding training courses. +// end::EN[] + diff --git a/docs/00b-basics/06-complementary-information.adoc b/docs/00b-basics/06-complementary-information.adoc new file mode 100644 index 0000000..0c0784b --- /dev/null +++ b/docs/00b-basics/06-complementary-information.adoc @@ -0,0 +1,12 @@ +// tag::DE[] +=== Ergänzende Informationen, Begriffe, Übersetzungen + +Soweit für das Verständnis des Lehrplans erforderlich, haben wir Fachbegriffe ins https://github.com/isaqb-org/glossary[iSAQB-Glossar] aufgenommen, definiert und bei Bedarf durch die Übersetzungen der Originalliteratur ergänzt. + +// end::DE[] + +// tag::EN[] +=== Supplementary Information, Terms, Translations + +To the extent necessary for understanding the curriculum, we have added definitions of technical terms to the https://github.com/isaqb-org/glossary[iSAQB glossary] and complemented them by references to (translated) literature. +// end::EN[] diff --git a/docs/01-module-block-1/00-structure.adoc b/docs/01-module-block-1/00-structure.adoc new file mode 100644 index 0000000..2966359 --- /dev/null +++ b/docs/01-module-block-1/00-structure.adoc @@ -0,0 +1,20 @@ +// header file for curriculum section 1: ERSTE LERNEINHEIT +// (c) iSAQB e.V. (https://isaqb.org) +// ==================================================== + + +// tag::DE[] +== Dies ist der Titel des ersten Moduls +// end::DE[] + +// tag::EN[] +== This is the First Module's Title +// end::EN[] + + +include::01-duration-terms.adoc[{include_configuration}] + +include::02-learning-goals.adoc[{include_configuration}] + +// references (if any!) +include::references.adoc[{include_configuration}] diff --git a/docs/01-module-block-1/01-duration-terms.adoc b/docs/01-module-block-1/01-duration-terms.adoc new file mode 100644 index 0000000..4b289d5 --- /dev/null +++ b/docs/01-module-block-1/01-duration-terms.adoc @@ -0,0 +1,29 @@ +// tag::DE[] +|=== +| Dauer: XXX Min. | Übungszeit: XXX Min. +|=== + +=== Begriffe und Konzepte +Begriff 1, Begriff 2, Begriff 3 + +// end::DE[] + +// tag::EN[] +|=== +| Duration: XXX min | Practice time: XXX min +|=== + +=== Terms and Principles +Term 1, Term 2, Term 3 +// end::EN[] + + +[NOTE] +==== +Überschrift in 00-structure.adoc ersetzen +==== + +[NOTE] +==== +Sinnvolle Zeiten für Dauer und Übungszeit eintragen, vernünftige Begriffe aufzählen. +==== diff --git a/docs/01-module-block-1/02-learning-goals.adoc b/docs/01-module-block-1/02-learning-goals.adoc new file mode 100644 index 0000000..a6efecc --- /dev/null +++ b/docs/01-module-block-1/02-learning-goals.adoc @@ -0,0 +1,26 @@ +=== {learning-goals} + +// tag::DE[] +[[LZ-1-1]] +==== LZ 1-1: Dies ist das erste Lernziel, in Kategorie xy +Hier wird beschrieben, was Teilnehmer:innen in diesem Lernziel lernen sollen. Das kann in Prosa-Text +in ganzen Sätzen oder in Aufzählungen mit Unterpunkten erfolgen. Dabei kann auch unterschieden werden, +wie wichtig einzelne Aspekte des Lernziels sind. Es kann hier bereits auf Literatur verwiesen werden. + +* Erstes Teilziel +* Zweites Unterthema +* Dritter Aspekt + + +// end::DE[] + +// tag::EN[] +[[LG-1-1]] +==== LG 1-1: The is the first learning goal, in category xy +tbd. +// end::EN[] + +[NOTE] +==== +Die einzelnen Lernziele müssen nicht als einfache Aufzählungen mit Unterpunkten aufgeführt werden, sondern können auch gerne in ganzen Sätzen formuliert werden, welche die einzelnen Punkte (sofern möglich) integrieren. +==== diff --git a/docs/01-module-block-1/references.adoc b/docs/01-module-block-1/references.adoc new file mode 100644 index 0000000..8fb3e41 --- /dev/null +++ b/docs/01-module-block-1/references.adoc @@ -0,0 +1,14 @@ +=== {references} + +<>, <>, <>, <> + + + +[NOTE] +==== +Eine Quelle wird über `\<