Merge pull request #18 from linuxserver/readme-typo

aptalca · web-flow · commit 27d9d961acc8 · 2020-10-04T10:44:21.000-04:00
fix readme typo, update templates
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,122 @@
+# Contributing to swag
+
+## Gotchas
+
+* While contributing make sure to make all your changes before creating a Pull Request, as our pipeline builds each commit after the PR is open.
+* Read, and fill the Pull Request template
+  * If this is a fix for a typo in code or documentation in the README please file an issue
+  * If the PR is addressing an existing issue include, closes #\<issue number>, in the body of the PR commit message
+* If you want to discuss changes, you can also bring it up in [#dev-talk](https://discordapp.com/channels/354974912613449730/757585807061155840) in our [Discord server](https://discord.gg/YWrKVTn)
+
+## Common files
+
+| File | Use case |
+| :----: | --- |
+| `Dockerfile` | Dockerfile used to build amd64 images |
+| `Dockerfile.aarch64` | Dockerfile used to build 64bit ARM architectures |
+| `Dockerfile.armhf` | Dockerfile used to build 32bit ARM architectures |
+| `Jenkinsfile` | This file is a product of our builder and should not be edited directly. This is used to build the image |
+| `jenkins-vars.yml` | This file is used to generate the `Jenkinsfile` mentioned above, it only affects the build-process |
+| `package_versions.txt` | This file is generated as a part of the build-process and should not be edited directly. It lists all the installed packages and their versions |
+| `README.md` | This file is a product of our builder and should not be edited directly. This displays the readme for the repository and image registries |
+| `readme-vars.yml` | This file is used to generate the `README.md` |
+
+## Readme
+
+If you would like to change our readme, please __**do not**__ directly edit the readme, as it is auto-generated on each commit.
+Instead edit the [readme-vars.yml](https://github.com/linuxserver/docker-swag/edit/master/readme-vars.yml).
+
+These variables are used in a template for our [Jenkins Builder](https://github.com/linuxserver/docker-jenkins-builder) as part of an ansible play.
+Most of these variables are also carried over to [docs.linuxserver.io](https://docs.linuxserver.io/images/docker-swag)
+
+### Fixing typos or clarify the text in the readme
+
+There are variables for multiple parts of the readme, the most common ones are:
+
+| Variable | Description |
+| :----: | --- |
+| `project_blurb` | This is the short excerpt shown above the project logo. |
+| `app_setup_block` | This is the text that shows up under "Application Setup" if enabled |
+
+### Parameters
+
+The compose and run examples are also generated from these variables.
+
+We have a [reference file](https://github.com/linuxserver/docker-jenkins-builder/blob/master/vars/_container-vars-blank) in our Jenkins Builder.
+
+These are prefixed with `param_` for required parameters, or `opt_param` for optional parameters, except for `cap_add`.
+Remember to enable param, if currently disabled. This differs between parameters, and can be seen in the reference file.
+
+Devices, environment variables, ports and volumes expects its variables in a certain way.
+
+### Devices
+
+```yml
+param_devices:
+  - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" }
+opt_param_devices:
+  - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" }
+```
+
+### Environment variables
+
+```yml
+param_env_vars:
+  - { env_var: "TZ", env_value: "Europe/London", desc: "Specify a timezone to use EG Europe/London." }
+opt_param_env_vars:
+  - { env_var: "VERSION", env_value: "latest", desc: "Supported values are LATEST, PLEXPASS or a specific version number." }
+```
+
+### Ports
+
+```yml
+param_ports:
+  - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" }
+opt_param_ports:
+  - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" }
+```
+
+### Volumes
+
+```yml
+param_volumes:
+  - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." }
+opt_param_volumes:
+  - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." }
+```
+
+### Testing template changes
+
+After you make any changes to the templates, you can use our [Jenkins Builder](https://github.com/linuxserver/docker-jenkins-builder) to have the files updated from the modified templates. Please use the command found under `Running Locally` [on this page](https://github.com/linuxserver/docker-jenkins-builder/blob/master/README.md) to generate them prior to submitting a PR.
+
+## Dockerfiles
+
+We use multiple Dockerfiles in our repos, this is because sometimes some CPU architectures needs different packages to work.
+If you are proposing additional packages to be added, ensure that you added the packages to all the Dockerfiles in alphabetical order.
+
+### Testing your changes
+
+```
+git clone https://github.com/linuxserver/docker-swag.git
+cd docker-swag
+docker build \
+  --no-cache \
+  --pull \
+  -t linuxserver/swag:latest .
+```
+
+The ARM variants can be built on x86_64 hardware using `multiarch/qemu-user-static`
+```
+docker run --rm --privileged multiarch/qemu-user-static:register --reset
+```
+
+Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64`.
+
+## Update the chagelog
+
+If you are modifying the Dockerfiles or any of the startup scripts in [root](https://github.com/linuxserver/docker-swag/tree/master/root), add an entry to the changelog
+
+```yml
+changelogs:
+  - { date: "DD.MM.YY:", desc: "Added some love to templates" }
+```
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -1,7 +1,10 @@
 [linuxserverurl]: https://linuxserver.io
 [![linuxserver.io](https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/linuxserver_medium.png)][linuxserverurl]
 
-If you are new to Docker or this application our issue tracker is **ONLY** used for reporting bugs or requesting features. Please use [our discord server](https://discord.gg/YWrKVTn) for general support.
+<!--- If you are new to Docker or this application our issue tracker is **ONLY** used for reporting bugs or requesting features. Please use [our discord server](https://discord.gg/YWrKVTn) for general support. --->
+
+<!--- If this acts as a feature request please ask yourself if this modification is something the whole userbase will benefit from --->
+<!--- If this is a specific change for corner case functionality or plugins please look at making a Docker Mod or local script  https://blog.linuxserver.io/2019/09/14/customizing-our-containers/ -->
 
 <!--- Provide a general summary of the issue in the Title above -->
 
@@ -22,9 +25,10 @@ If you are new to Docker or this application our issue tracker is **ONLY** used
 4.
 
 ## Environment
-**OS:**      
-**CPU architecture:** x86_64/arm32/arm64      
-**How docker service was installed:**      
+**OS:**
+**CPU architecture:** x86_64/arm32/arm64
+**How docker service was installed:**
+<!--- ie. from the official docker repo, from the distro repo, nas OS provided, etc. -->
 <!--- Providing context helps us come up with a solution that is most useful in the real world -->
 
 ## Command used to create docker container (run/create/compose/screenshot)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,11 +2,11 @@
 
 [linuxserverurl]: https://linuxserver.io
 [![linuxserver.io](https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/linuxserver_medium.png)][linuxserverurl]
-	
+
 
 <!--- Before submitting a pull request please check the following -->
 
-<!---  If this is a fix for a typo in code or documentation in the README please file an issue and let us sort it out we do not need a PR  --> 
+<!---  If this is a fix for a typo in code or documentation in the README please file an issue and let us sort it out we do not need a PR  -->
 <!---  Ask yourself if this modification is something the whole userbase will benefit from, if this is a specific change for corner case functionality or plugins please look at making a Docker Mod or local script  https://blog.linuxserver.io/2019/09/14/customizing-our-containers/ -->
 <!---  That if the PR is addressing an existing issue include, closes #<issue number> , in the body of the PR commit message   -->
 <!---  You have included links to any files / patches etc your PR may be using in the body of the PR commit message -->
@@ -21,7 +21,11 @@
 
 ------------------------------
 
-We welcome all PR’s though this doesn’t guarantee it will be accepted.
+ - [ ] I have read the [contributing](https://github.com/linuxserver/docker-swag/blob/master/.github/CONTRIBUTING.md) guideline and understand that I have made the correct modifications
+
+------------------------------
+
+<!--- We welcome all PR’s though this doesn’t guarantee it will be accepted. -->
 
 ## Description:
 <!--- Describe your changes in detail -->
diff --git a/.github/workflows/greetings.yml b/.github/workflows/greetings.yml
@@ -8,6 +8,6 @@ jobs:
     steps:
     - uses: actions/first-interaction@v1
       with:
-        issue-message: 'Thanks for opening your first issue here! Be sure to follow the [issue template](https://github.com/linuxserver/docker-swag/.github/ISSUE_TEMPLATE.md)!'
-        pr-message: 'Thanks for opening this pull request! Be sure to follow the [pull request template](https://github.com/linuxserver/docker-swag/.github/PULL_REQUEST_TEMPLATE.md)!'
+        issue-message: 'Thanks for opening your first issue here! Be sure to follow the [issue template](https://github.com/linuxserver/docker-swag/blob/master/.github/ISSUE_TEMPLATE.md)!'
+        pr-message: 'Thanks for opening this pull request! Be sure to follow the [pull request template](https://github.com/linuxserver/docker-swag/blob/master/.github/PULL_REQUEST_TEMPLATE.md)!'
         repo-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/Jenkinsfile b/Jenkinsfile
@@ -56,7 +56,7 @@ pipeline {
           env.CODE_URL = 'https://github.com/' + env.LS_USER + '/' + env.LS_REPO + '/commit/' + env.GIT_COMMIT
           env.DOCKERHUB_LINK = 'https://hub.docker.com/r/' + env.DOCKERHUB_IMAGE + '/tags/'
           env.PULL_REQUEST = env.CHANGE_ID
-          env.TEMPLATED_FILES = 'Jenkinsfile README.md LICENSE ./.github/FUNDING.yml ./.github/ISSUE_TEMPLATE.md ./.github/PULL_REQUEST_TEMPLATE.md ./.github/workflows/greetings.yml ./.github/workflows/stale.yml ./root/donate.txt'
+          env.TEMPLATED_FILES = 'Jenkinsfile README.md LICENSE ./.github/CONTRIBUTING.md ./.github/FUNDING.yml ./.github/ISSUE_TEMPLATE.md ./.github/PULL_REQUEST_TEMPLATE.md ./.github/workflows/greetings.yml ./.github/workflows/stale.yml ./root/donate.txt'
         }
         script{
           env.LS_RELEASE_NUMBER = sh(
@@ -136,6 +136,7 @@ pipeline {
             env.CI_TAGS = env.EXT_RELEASE_CLEAN + '-ls' + env.LS_TAG_NUMBER
           }
           env.META_TAG = env.EXT_RELEASE_CLEAN + '-ls' + env.LS_TAG_NUMBER
+          env.EXT_RELEASE_TAG = 'version-' + env.EXT_RELEASE_CLEAN
         }
       }
     }
@@ -156,6 +157,7 @@ pipeline {
             env.CI_TAGS = env.EXT_RELEASE_CLEAN + '-pkg-' + env.PACKAGE_TAG + '-dev-' + env.COMMIT_SHA
           }
           env.META_TAG = env.EXT_RELEASE_CLEAN + '-pkg-' + env.PACKAGE_TAG + '-dev-' + env.COMMIT_SHA
+          env.EXT_RELEASE_TAG = 'version-' + env.EXT_RELEASE_CLEAN
           env.DOCKERHUB_LINK = 'https://hub.docker.com/r/' + env.DEV_DOCKERHUB_IMAGE + '/tags/'
         }
       }
@@ -176,6 +178,7 @@ pipeline {
             env.CI_TAGS = env.EXT_RELEASE_CLEAN + '-pkg-' + env.PACKAGE_TAG + '-pr-' + env.PULL_REQUEST
           }
           env.META_TAG = env.EXT_RELEASE_CLEAN + '-pkg-' + env.PACKAGE_TAG + '-pr-' + env.PULL_REQUEST
+          env.EXT_RELEASE_TAG = 'version-' + env.EXT_RELEASE_CLEAN
           env.CODE_URL = 'https://github.com/' + env.LS_USER + '/' + env.LS_REPO + '/pull/' + env.PULL_REQUEST
           env.DOCKERHUB_LINK = 'https://hub.docker.com/r/' + env.PR_DOCKERHUB_IMAGE + '/tags/'
         }
@@ -543,15 +546,18 @@ pipeline {
                   for PUSHIMAGE in "${GITHUBIMAGE}" "${GITLABIMAGE}" "${IMAGE}"; do
                     docker tag ${IMAGE}:${META_TAG} ${PUSHIMAGE}:${META_TAG}
                     docker tag ${PUSHIMAGE}:${META_TAG} ${PUSHIMAGE}:latest
+                    docker tag ${PUSHIMAGE}:${META_TAG} ${PUSHIMAGE}:${EXT_RELEASE_TAG}
                     docker push ${PUSHIMAGE}:latest
                     docker push ${PUSHIMAGE}:${META_TAG}
+                    docker push ${PUSHIMAGE}:${EXT_RELEASE_TAG}
                   done
                '''
           }
           sh '''#! /bin/bash
                 for DELETEIMAGE in "${GITHUBIMAGE}" "{GITLABIMAGE}" "${IMAGE}"; do
                   docker rmi \
                   ${DELETEIMAGE}:${META_TAG} \
+                  ${DELETEIMAGE}:${EXT_RELEASE_TAG} \
                   ${DELETEIMAGE}:latest || :
                 done
              '''
@@ -592,12 +598,18 @@ pipeline {
                     docker tag ${MANIFESTIMAGE}:amd64-${META_TAG} ${MANIFESTIMAGE}:amd64-latest
                     docker tag ${MANIFESTIMAGE}:arm32v7-${META_TAG} ${MANIFESTIMAGE}:arm32v7-latest
                     docker tag ${MANIFESTIMAGE}:arm64v8-${META_TAG} ${MANIFESTIMAGE}:arm64v8-latest
+                    docker tag ${MANIFESTIMAGE}:amd64-${META_TAG} ${MANIFESTIMAGE}:amd64-${EXT_RELEASE_TAG}
+                    docker tag ${MANIFESTIMAGE}:arm32v7-${META_TAG} ${MANIFESTIMAGE}:arm32v7-${EXT_RELEASE_TAG}
+                    docker tag ${MANIFESTIMAGE}:arm64v8-${META_TAG} ${MANIFESTIMAGE}:arm64v8-${EXT_RELEASE_TAG}
                     docker push ${MANIFESTIMAGE}:amd64-${META_TAG}
                     docker push ${MANIFESTIMAGE}:arm32v7-${META_TAG}
                     docker push ${MANIFESTIMAGE}:arm64v8-${META_TAG}
                     docker push ${MANIFESTIMAGE}:amd64-latest
                     docker push ${MANIFESTIMAGE}:arm32v7-latest
                     docker push ${MANIFESTIMAGE}:arm64v8-latest
+                    docker push ${MANIFESTIMAGE}:amd64-${EXT_RELEASE_TAG}
+                    docker push ${MANIFESTIMAGE}:arm32v7-${EXT_RELEASE_TAG}
+                    docker push ${MANIFESTIMAGE}:arm64v8-${EXT_RELEASE_TAG}
                     docker manifest push --purge ${MANIFESTIMAGE}:latest || :
                     docker manifest create ${MANIFESTIMAGE}:latest ${MANIFESTIMAGE}:amd64-latest ${MANIFESTIMAGE}:arm32v7-latest ${MANIFESTIMAGE}:arm64v8-latest
                     docker manifest annotate ${MANIFESTIMAGE}:latest ${MANIFESTIMAGE}:arm32v7-latest --os linux --arch arm
@@ -606,8 +618,12 @@ pipeline {
                     docker manifest create ${MANIFESTIMAGE}:${META_TAG} ${MANIFESTIMAGE}:amd64-${META_TAG} ${MANIFESTIMAGE}:arm32v7-${META_TAG} ${MANIFESTIMAGE}:arm64v8-${META_TAG}
                     docker manifest annotate ${MANIFESTIMAGE}:${META_TAG} ${MANIFESTIMAGE}:arm32v7-${META_TAG} --os linux --arch arm
                     docker manifest annotate ${MANIFESTIMAGE}:${META_TAG} ${MANIFESTIMAGE}:arm64v8-${META_TAG} --os linux --arch arm64 --variant v8
+                    docker manifest create ${MANIFESTIMAGE}:${EXT_RELEASE_TAG} ${MANIFESTIMAGE}:amd64-${EXT_RELEASE_TAG} ${MANIFESTIMAGE}:arm32v7-${EXT_RELEASE_TAG} ${MANIFESTIMAGE}:arm64v8-${EXT_RELEASE_TAG}
+                    docker manifest annotate ${MANIFESTIMAGE}:${EXT_RELEASE_TAG} ${MANIFESTIMAGE}:arm32v7-${EXT_RELEASE_TAG} --os linux --arch arm
+                    docker manifest annotate ${MANIFESTIMAGE}:${EXT_RELEASE_TAG} ${MANIFESTIMAGE}:arm64v8-${EXT_RELEASE_TAG} --os linux --arch arm64 --variant v8
                     docker manifest push --purge ${MANIFESTIMAGE}:latest
                     docker manifest push --purge ${MANIFESTIMAGE}:${META_TAG} 
+                    docker manifest push --purge ${MANIFESTIMAGE}:${EXT_RELEASE_TAG} 
                   done
                   docker tag ${IMAGE}:amd64-${META_TAG} ${GITHUBIMAGE}:amd64-${META_TAG}
                   docker tag ${IMAGE}:arm32v7-${META_TAG} ${GITHUBIMAGE}:arm32v7-${META_TAG}
@@ -616,13 +632,21 @@ pipeline {
                   docker tag ${GITHUBIMAGE}:amd64-${META_TAG} ${GITHUBIMAGE}:${META_TAG}
                   docker tag ${GITHUBIMAGE}:arm32v7-${META_TAG} ${GITHUBIMAGE}:arm32v7-latest
                   docker tag ${GITHUBIMAGE}:arm64v8-${META_TAG} ${GITHUBIMAGE}:arm64v8-latest
+                  docker tag ${GITHUBIMAGE}:amd64-${META_TAG} ${GITHUBIMAGE}:amd64-${EXT_RELEASE_TAG}
+                  docker tag ${GITHUBIMAGE}:amd64-${META_TAG} ${GITHUBIMAGE}:${EXT_RELEASE_TAG}
+                  docker tag ${GITHUBIMAGE}:arm32v7-${META_TAG} ${GITHUBIMAGE}:arm32v7-${EXT_RELEASE_TAG}
+                  docker tag ${GITHUBIMAGE}:arm64v8-${META_TAG} ${GITHUBIMAGE}:arm64v8-${EXT_RELEASE_TAG}
                   docker push ${GITHUBIMAGE}:amd64-${META_TAG}
                   docker push ${GITHUBIMAGE}:arm32v7-${META_TAG}
                   docker push ${GITHUBIMAGE}:arm64v8-${META_TAG}
                   docker push ${GITHUBIMAGE}:latest
                   docker push ${GITHUBIMAGE}:${META_TAG}
                   docker push ${GITHUBIMAGE}:arm32v7-latest
                   docker push ${GITHUBIMAGE}:arm64v8-latest
+                  docker push ${GITHUBIMAGE}:${EXT_RELEASE_TAG}
+                  docker push ${GITHUBIMAGE}:amd64-${EXT_RELEASE_TAG}
+                  docker push ${GITHUBIMAGE}:arm32v7-${EXT_RELEASE_TAG}
+                  docker push ${GITHUBIMAGE}:arm64v8-${EXT_RELEASE_TAG}
                '''
           }
           sh '''#! /bin/bash
@@ -691,7 +715,7 @@ pipeline {
                 set -e
                 TEMPDIR=$(mktemp -d)
                 docker pull linuxserver/jenkins-builder:latest
-                docker run --rm -e CONTAINER_NAME=${CONTAINER_NAME} -e GITHUB_BRANCH=master -v ${TEMPDIR}:/ansible/jenkins linuxserver/jenkins-builder:latest 
+                docker run --rm -e CONTAINER_NAME=${CONTAINER_NAME} -e GITHUB_BRANCH="${BRANCH_NAME}" -v ${TEMPDIR}:/ansible/jenkins linuxserver/jenkins-builder:latest 
                 docker pull lsiodev/readme-sync
                 docker run --rm=true \
                   -e DOCKERHUB_USERNAME=$DOCKERUSER \
diff --git a/README.md b/README.md
diff --git a/readme-vars.yml b/readme-vars.yml
