diff --git a/README.md b/README.md index a14f794..87715c7 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,150 @@ -# Template for `Application Examples` +# Template for `Application Examples` on GitHub ## What is an application example -An application example ist a stand alone project, which demonstrates the usage of one ore more features or libraries. This template is optimized for a creation of application examples for PLC applications (executable on a PLCSIM Advanced or real PLC S7-1500). +An application example is a standalone project, which demonstrates the usage of one ore more features or libraries. This template is optimized for the creation of application examples of PLC applications (executable on a PLCSIM Advanced or real PLC S7-1500). -## Create a project from this template +## Create a project from this "apax-template" -Example: If you want to create an application example `ae-motion-control` then use this template by entering: +If you want to create a new Github application example in this community please start with using this apax-template by entering the following in the terminal : ```bash -apax create @simatic-ax/app --registry https://npm.pkg.github.com ae-motion-control +apax create @simatic-ax/app --registry https://npm.pkg.github.com ``` -## Create an application example on GitHub +## Folder-structure of this "app" apax-template -Example: An application example `ae-motion-control` should be created. +```bash +app + | + +- .github + | | # default GitHub workflows any gh-community-scope app-repo should have (ignore) + | +- lint-repo.yml + | +- release-applicationexample.yml + | + +- docs + | | # the place for additional user-documentation + | +- app.md + | + +- src + | | # adjust and add user-programs here + | +- Configuration.st + | +- MainProgram.st + | + +- test + | | # adjust and add test-programs here + | +- dummy.st + | + +- watchlist + | | # adjust and add your watchlists here + | +- default.mon + | + | # additional meta-information for GitHub/-workflows (ignore) + +- .gitattributes + +- .gitignore + +- .markdownlint.yml + +- apax-files-section.yml + | # adjust the project description file / add apax-scripts + +- apax.yml + | # essential git project files, pls. adjust + +- CODEOWNERS + +- README.md + +- LICENSE.md +``` + +## Create an `application example` repository with this apax-template on GitHub + +Step-by-step instructions: for creating & releasing `ae-motion-control` (case example) 1. Create a repository `ae-motion-control` on GitHub - ![newrepo](docs/newrepo.png) + This repository is tailored to be in sync with your local git-repository which holds on to your actual application program. + + Purpose: Later people can create local clones/ forks from the repository and all its files. + + ![newrepo](docs/images/newrepo.png) + + ![reponame1](docs/images/reponame1.png) + + - For the actual "Repository name" always start with `ae- ...` + - As "Description" please start with `Application example:...`. + - If "public" or "private" depends on internal decisions. + +2. Add the secrets to the repository (only in the case if it's private) + + ![secrets](docs/images/secrets.png) + + > You don't know the secrets? Ask one of the owners or `@sjuergen` + +3. Create an additional repository `template-ae-motion-control` on GitHub + + Unlike the base repository, this "template-..." variant is just there for holding on to the application example apax package, which will be created automatically after a successful "release"-process on GitHub (release-pipeline with GitHub "workflows"). There is no need for you to further maintain this repository after the creation. - ![newrepo2](docs/newrepo2.png) + Purpose: Later people can use apax to "create" new projects based on that application project apax package (template functionality). - > If public or private depends is an internal decision + ![newrepo](docs/images/newrepo.png) -1. Add the secrets to the repository (only in the case if it's private) + ![reponame2](docs/images/reponame2.png) - ![secrets](docs/secrets.png) + - For the actual "Repository name" always start with `template-ae- ...`. + - As "Description" please use the following scheme: `Template "ae-" / dummy-repo`. + - If "public" or "private" depends on internal decisions. + - Add at least a "README.md" and a "LICENSE.md" file - > you don't know the secrets? Ask one of the owners or `@sjuergen` +4. Initiate your local repository -1. Create a repository `template-ae-motion-control` on GitHub which contains the apax package + Once this is done the remote core-repository on GitHub is ready to receive the application program from your local Git repository. - ![newrepo](docs/newrepo.png) + Therefore follow the steps below on your local system by navigating to your desired project directory. Open the terminal. - ![newrepo3](docs/newrepo3.png) +5. If not done yet, login to the GitHub registry first - > If public or private depends is an internal decision + ```bash + apax login --registry https://npm.pkg.github.com/ + ``` -1. If not done, login to the GitHub registry + Follow the instruction and type in your credentials. - ```bash - apax login --registry https://npm.pkg.github.com/ --password - ``` + More information you'll find [here](https://github.com/simatic-ax/.github/blob/main/docs/personalaccesstoken.md) - More information you'll find [here](https://github.com/simatic-ax/.github/blob/main/docs/personalaccesstoken.md) +6. Create a new project based on the GitHub app apax-template -1. Create the application example from the template + After a successful login you can follow-up with entering: - ```bash - apax create @simatic-ax/app --registry https://npm.pkg.github.com ae-motion-control - ``` + ```bash + apax create @simatic-ax/app --registry https://npm.pkg.github.com ae-motion-control + ``` -1. Add the remote repository to your local repository + Here: the application example will be named "ae-motion-control" and the project-folder now is predefined with the templates contents. - ```bash - git remote add origin git@github.com:simatic-ax/ae-motion-control.git - git push -u origin main - ``` +7. Connect the previous created remote GitHub repository to your local Git repository -1. Install dependencies + A apax "create" command will always initiate a local Git repository. This one must be synced with the "simatic-ax/ae-motion-control" GitHub repository now. - ```bash - apax install -L - ``` + ```bash + git remote add origin git@github.com:simatic-ax/ae-motion-control.git + ``` -1. Optionally update dependencies + ```bash + git push -u origin main + ``` - ```bash - apax update -a - ``` +8. Install the project dependencies -1. Now you can implement the application example + ```bash + apax install + ``` + +9. Optionally update its dependencies + + ```bash + apax update + ``` + +10. Now you can implement the application example + + Open the project-folder with AX-Code and start adjusting the files to fit your application example. Consider using Git branches and frequent commits in order to keep track of your changes. + Don't forget to sync your local changes with the git-remote repository on GitHub at some point. ## Release the application example @@ -83,44 +156,39 @@ Before you release the application example, all checks have to be done: - [ ] Patent Clearing - [ ] ECC (Export control with the [ecc wizzard](https://code-ops.code.siemens.io/ecc-wizard/)) - [ ] License is up to date -- [ ] The readme contains a description: +- [ ] Codeowner are up to date +- [ ] The Readme.md contains a description: - What is this application doing? - How to install the application example - How to start the application example - [ ] Application example has been reviewed + - Create an MergeRequest for your Main-branch and add community-admins as reviewer ### Release of the application example -![release](docs/release.png) +Successfully releasing your application example will automatically trigger the creation of an apax-package template of your current application-example within the "template-..." Github repository. Depending on the used workflows the base repository may have to succeed linter and other checks in order to do so. Be aware of failing pipelines (GitHub workflows). -## Structure of this template +Draft a new "Release"-tag within your base GitHub repository -```bash -app - | - +- .github - | +- github-action-release-ae.yml - | - +- docs - | | - | +- app.md - | - +- src - | +- Configuration.st - | +- MainProgram.st - | - +- test - | +- dummy.st - | - +- watchlist - | +- default.mon - | - +- .gitignore - +- apax.yml - +- LICENSE.md - +- README.md -``` +- choose an appropriate version tag +- choose an appropriate release-title +- let github generate release-notes +- publish release + +![release1](docs/images/release1.png) +![release2](docs/images/release2.png) +![release3](docs/images/release3.png) + +> This action may only can be performed by one of the community-admins. + +## Congratulations πŸ±β€πŸ + +You finally contributed to the simatic-ax community offering apax-packages for everyone by simply using apax. + +KEEP GOING πŸ±β€πŸ’»! + +> BE AWARE: Only successful GitHub workflows (pipelines) will create the package at our GitHub package-registry (scope: @simatic-ax). ## Learn More -See the [documentation on custom templates](https://axciteme.siemens.com/docs/apax/templates). +See the [documentation on custom templates](https://console.simatic-ax.siemens.io/docs/apax/templates). diff --git a/docs/newrepo.png b/docs/images/newrepo.png similarity index 100% rename from docs/newrepo.png rename to docs/images/newrepo.png diff --git a/docs/images/release1.png b/docs/images/release1.png new file mode 100644 index 0000000..7d07f1d Binary files /dev/null and b/docs/images/release1.png differ diff --git a/docs/images/release2.png b/docs/images/release2.png new file mode 100644 index 0000000..4082172 Binary files /dev/null and b/docs/images/release2.png differ diff --git a/docs/images/release3.png b/docs/images/release3.png new file mode 100644 index 0000000..d552805 Binary files /dev/null and b/docs/images/release3.png differ diff --git a/docs/newrepo2.png b/docs/images/reponame1.png similarity index 100% rename from docs/newrepo2.png rename to docs/images/reponame1.png diff --git a/docs/newrepo3.png b/docs/images/reponame2.png similarity index 100% rename from docs/newrepo3.png rename to docs/images/reponame2.png diff --git a/docs/secrets.png b/docs/images/secrets.png similarity index 100% rename from docs/secrets.png rename to docs/images/secrets.png diff --git a/docs/release.png b/docs/release.png deleted file mode 100644 index cc1b12c..0000000 Binary files a/docs/release.png and /dev/null differ diff --git a/template/.gitattributes b/template/.gitattributes index 2c78092..61be65b 100644 --- a/template/.gitattributes +++ b/template/.gitattributes @@ -1,2 +1,2 @@ ο»Ώ# `.gitattributes` reclassify `.st` files as iec-st: -** linguist-vendored +** linguist-vendored \ No newline at end of file diff --git a/template/.github/workflows/release-applicationexample.yml b/template/.github/workflows/release-applicationexample.yml index eee017d..17084f3 100644 --- a/template/.github/workflows/release-applicationexample.yml +++ b/template/.github/workflows/release-applicationexample.yml @@ -13,4 +13,4 @@ jobs: with: VERSION: ${{ github.ref_name }} - PROJECT_NAME: ae-trafficlight + PROJECT_NAME: apax-package-name-d7b4b031 \ No newline at end of file diff --git a/template/.gitignore b/template/.gitignore index 60ad0a1..81447e9 100644 --- a/template/.gitignore +++ b/template/.gitignore @@ -2,4 +2,4 @@ .env bin obj -testresult +testresult \ No newline at end of file diff --git a/template/README.md b/template/README.md index 51f6943..f6d373b 100644 --- a/template/README.md +++ b/template/README.md @@ -1,49 +1,60 @@ -# apax-package-name-d7b4b031 +# @simatic-ax/apax-package-name-d7b4b031 ## What is this application doing? +> This README.md was generated by a template. +> Please adjust/complete ... + ## Install the application example and open it locally +Example Text: + 1. Open a command line interface (CLI) and switch to the target folder like: - ```sh - D: - cd \Examples - ``` + ```cli + D: + cd \Examples + ``` -1. Install the application example and open it with `AX Code` +2. Install the application example and open it with `AX Code` + + Run the following commands in a CLI + + ```cli + apax create @simatic-ax/apax-package-name-d7b4b031 --registry https://npm.pkg.github.com apax-package-name-d7b4b031 + axcode apax-package-name-d7b4b031 + ``` - Run the following commands in a CLI +3. ... - ```sh - apax create @simatic-ax/apax-package-name-d7b4b031 --registry https://npm.pkg.github.com apax-package-name-d7b4b031 - axcode apax-package-name-d7b4b031 - ``` +> This README.md was generated by a template. +> Please adjust/complete ... ## Setup the application example -1. Start a PLCSIM Advanced Instance or using a 1500 PLC. Download a TIA Portal created HWCN with a 1500 standard PLC (Default IP Address 192.168.0.1). +Example Text: - > The default ip address can be changed in the apax.yml -> - > ```yml - > IP_ADDRESS: "192.168.0.1" - > ``` +1. Start a PLCSIM Advanced Instance or use a 1500 PLC. Download a TIA Portal created HWCN with a 1500 standard PLC (Default IP Address 192.168.0.1). The default ip address can be changed in the apax.yml: -1. If not open, open a terminal in AX Code (`CTRL+SHIFT+ΓΆ`) + ```yml + IP_ADDRESS: "192.168.0.1" + ``` -## Start the application example +2. ... - The application example can be started with the following command: +> This README.md was generated by a template. +> Please adjust/complete ... - ```cli - apax start [1500] - ``` +## Start the application example - > `1500` is required, if you use a real 1500 PLC instead of PLCSIM Advanced. +> This README.md was generated by a template. +> Please adjust/complete ... ## Further information +> This README.md was generated by a template. +> Please adjust/complete ... + ## License and Legal information Please read the [Legal information](LICENSE.md) diff --git a/template/apax-files-section.yml b/template/apax-files-section.yml index d5d1245..fc22d6a 100644 --- a/template/apax-files-section.yml +++ b/template/apax-files-section.yml @@ -8,4 +8,4 @@ files: - '!**/.gitattributes' - '!**/.markdownlint.yml' - '!template/CODEOWNERS' - - '!template/apax-files-section.yml' + - '!template/apax-files-section.yml' \ No newline at end of file diff --git a/template/apax.yml b/template/apax.yml index 5f5d810..2868b87 100644 --- a/template/apax.yml +++ b/template/apax.yml @@ -2,44 +2,45 @@ name: "@simatic-ax/apax-package-name-d7b4b031" version: 0.0.1 author: Siemens AG +type: app # Description for your application example or app description: -type: app #URL to the repository repository: type: git url: https://github.com/simatic-ax/apax-package-name-d7b4b031 -# Environment variables +# Targets to be compiled with 'apax build' +targets: + - "1500" + - "llvm" + +# Registry information, to other npm-registries where Apax packages are located +registries: + '@simatic-ax': 'https://npm.pkg.github.com/' +# Install settings +installStrategy: strict +apaxVersion: 3.2.1 +# Dependencies +devDependencies: + "@ax/sdk": 2405.0.0 + "@simatic-ax/snippetscollection": 1.0.0 +dependencies: + "@ax/system": 7.0.17 # this is an example lib-dependency for your code, pls. adjust + +# Project variables variables: APAX_BUILD_ARGS: - - --debug # Enable debug information for value debugging - # Choose bin-folder. Depending on your target. - # BIN_FOLDER: "./bin/1500" # choose for target S7-1500 PLC - BIN_FOLDER: "./bin/plcsim" # choose for target PLCSIM Advanced + - --debug # Enable debug information for value debugging + BIN_FOLDER: "./bin/1500" # choose your target RT, here : any S7-1500 PLC # IP address must match with the IP address of your target device # The IP address in the .vscode/launch.json must be equal IP_ADDRESS: "192.168.0.1" -# targets to be compiled with apax build -targets: - - "1500" - - "plcsim" - - "llvm" + # Apax scripts scripts: # call 'apax load' to download the builded program to the target. An 'apax build' might be required upfront - load: apax sld load --input $BIN_FOLDER --target $IP_ADDRESS --restart - --accept-security-disclaimer --log debug - # call 'apax dlsim' to build and download the application to the target - dlsim: + load: apax sld load --input $BIN_FOLDER --target $IP_ADDRESS --restart --accept-security-disclaimer --log debug + # call 'apax dlplc' to build and download the application to the target + dlplc: - apax build - - apax load -# Dependencies -devDependencies: - "@ax/sdk": 2311.0.1 - "@simatic-ax/snippetscollection": 1.0.0 - "@ax/trace": 2.7.0 -# Registry information, to other npm registries where Apax packages are located -registries: - '@simatic-ax': 'https://npm.pkg.github.com/' -installStrategy: strict -apaxVersion: 3.1.0 + - apax load \ No newline at end of file diff --git a/template/repolint.json b/template/repolint.json new file mode 100644 index 0000000..4dff505 --- /dev/null +++ b/template/repolint.json @@ -0,0 +1,158 @@ +{ + "$schema": "./schema.json", + "version": 2, + "axioms": { + "linguist": "language", + "licensee": "license", + "packagers": "packager" + }, + "rules": { + "license-file-exists": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ "LICENSE.md" ], + "nocase": true + } + } + }, + "readme-file-exists": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ "README*.md" ], + "nocase": true + } + } + }, + "readme-references-license": { + "level": "error", + "rule": { + "type": "file-contents", + "options": { + "globsAll": [ "README*" ], + "content": "license", + "flags": "i" + } + } + }, + "binaries-not-present": { + "level": "warning", + "rule": { + "type": "file-type-exclusion", + "options": { + "type": [ "**/*.exe", "**/*.dll", "!node_modules/**" ] + } + } + }, + "test-directory-exists": { + "level": "warning", + "rule": { + "type": "directory-existence", + "options": { + "globsAny": [ "**/test*" ], + "nocase": true + } + } + }, + "source-directory-exists": { + "level": "warning", + "rule": { + "type": "directory-existence", + "options": { + "globsAny": [ "**/src*" ], + "nocase": true + } + } + }, + "additional-docs-directory-exists": { + "level": "warning", + "rule": { + "type": "directory-existence", + "options": { + "globsAny": [ "**/docs*" ], + "nocase": true + } + } + }, + "integrates-with-ci": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + ".github/workflows/*" + ] + } + } + }, + "markdownlint-config-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + ".markdownlint.yml" + ] + } + } + }, + "apax-yml-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + "apax.yml" + ] + } + } + }, + "gitignore-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + ".gitignore" + ] + } + } + }, + "gitattributes-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + ".gitattributes" + ] + } + } + }, + "apax-files-section-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + "apax-files-section.yml" + ] + } + } + }, + "CODEOWNERS-exit": { + "level": "error", + "rule": { + "type": "file-existence", + "options": { + "globsAny": [ + "CODEOWNERS" + ] + } + } + } + } +}