Fix/documentation_chore/apaxyml

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-<your-app-name>" / 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 <your personal access token>
-    ```
+   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 [email protected]: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 [email protected]: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).

template/.gitattributes

@@ -1,2 +1,2 @@
 # `.gitattributes` reclassify `.st` files as iec-st:
-** linguist-vendored
+** linguist-vendored

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

template/.gitignore

@@ -2,4 +2,4 @@
 .env
 bin
 obj
-testresult
+testresult

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)

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'