|
1 | | -# Contributing to lidarr |
| 1 | +# Contributing to docker-lidarr |
2 | 2 |
|
3 | | -## Gotchas |
| 3 | +Thank you for taking the time to contribute to this project. |
| 4 | +We appreciate all contributions, but please follow the guidelines below to ensure a smooth review process and CI pipeline execution. |
4 | 5 |
|
5 | | -* 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. |
6 | | -* Read, and fill the Pull Request template |
7 | | - * If this is a fix for a typo (in code, documentation, or the README) please file an issue and let us sort it out. We do not need a PR |
8 | | - * If the PR is addressing an existing issue include, closes #\<issue number>, in the body of the PR commit message |
9 | | -* 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://linuxserver.io/discord) |
| 6 | +--- |
10 | 7 |
|
11 | | -## Common files |
| 8 | +## Important guidelines (read first) |
12 | 9 |
|
13 | | -| File | Use case | |
14 | | -| :----: | --- | |
15 | | -| `Dockerfile` | Dockerfile used to build amd64 images | |
16 | | -| `Dockerfile.aarch64` | Dockerfile used to build 64bit ARM architectures | |
17 | | -| `Dockerfile.armhf` | Dockerfile used to build 32bit ARM architectures | |
18 | | -| `Jenkinsfile` | This file is a product of our builder and should not be edited directly. This is used to build the image | |
19 | | -| `jenkins-vars.yml` | This file is used to generate the `Jenkinsfile` mentioned above, it only affects the build-process | |
20 | | -| `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 | |
21 | | -| `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 | |
22 | | -| `readme-vars.yml` | This file is used to generate the `README.md` | |
| 10 | +- Make sure all changes are completed before opening a Pull Request. |
| 11 | + Our CI pipeline builds every commit after the PR is opened. |
23 | 12 |
|
24 | | -## Readme |
| 13 | +- Always fill out the Pull Request template completely. |
25 | 14 |
|
26 | | -If you would like to change our readme, please __**do not**__ directly edit the readme, as it is auto-generated on each commit. |
27 | | -Instead edit the [readme-vars.yml](https://github.com/linuxserver/docker-lidarr/edit/master/readme-vars.yml). |
| 15 | +- Do NOT open PRs for simple typos in documentation, code, or README. |
| 16 | + Instead, open an issue and we will handle it. |
28 | 17 |
|
29 | | -These variables are used in a template for our [Jenkins Builder](https://github.com/linuxserver/docker-jenkins-builder) as part of an ansible play. |
30 | | -Most of these variables are also carried over to [docs.linuxserver.io](https://docs.linuxserver.io/images/docker-lidarr) |
| 18 | +- If your PR fixes an existing issue, include: |
| 19 | + `closes #<issue number>` in the PR description or commit message. |
31 | 20 |
|
32 | | -### Fixing typos or clarify the text in the readme |
| 21 | +- For discussions and help: |
| 22 | + - Discord server: https://linuxserver.io/discord |
| 23 | + - Dev chat: https://discordapp.com/channels/354974912613449730/757585807061155840 |
33 | 24 |
|
34 | | -There are variables for multiple parts of the readme, the most common ones are: |
| 25 | +--- |
35 | 26 |
|
36 | | -| Variable | Description | |
37 | | -| :----: | --- | |
38 | | -| `project_blurb` | This is the short excerpt shown above the project logo. | |
39 | | -| `app_setup_block` | This is the text that shows up under "Application Setup" if enabled | |
| 27 | +## Repository structure overview |
| 28 | + |
| 29 | +| File | Purpose | |
| 30 | +|------|--------| |
| 31 | +| `Dockerfile` | AMD64 build definition | |
| 32 | +| `Dockerfile.aarch64` | ARM64 build definition | |
| 33 | +| `Dockerfile.armhf` | ARM32 build definition | |
| 34 | +| `Jenkinsfile` | Auto-generated CI pipeline (DO NOT EDIT) | |
| 35 | +| `jenkins-vars.yml` | Build configuration for Jenkins | |
| 36 | +| `package_versions.txt` | Generated package inventory | |
| 37 | +| `README.md` | Auto-generated documentation (DO NOT EDIT) | |
| 38 | +| `readme-vars.yml` | Source file for README generation | |
40 | 39 |
|
41 | | -### Parameters |
| 40 | +--- |
42 | 41 |
|
43 | | -The compose and run examples are also generated from these variables. |
| 42 | +## README changes |
44 | 43 |
|
45 | | -We have a [reference file](https://github.com/linuxserver/docker-jenkins-builder/blob/master/vars/_container-vars-blank) in our Jenkins Builder. |
| 44 | +⚠️ DO NOT edit `README.md` directly. |
46 | 45 |
|
47 | | -These are prefixed with `param_` for required parameters, or `opt_param` for optional parameters, except for `cap_add`. |
48 | | -Remember to enable param, if currently disabled. This differs between parameters, and can be seen in the reference file. |
| 46 | +All README changes must be made in: |
49 | 47 |
|
50 | | -Devices, environment variables, ports and volumes expects its variables in a certain way. |
| 48 | +https://github.com/linuxserver/docker-lidarr/edit/master/readme-vars.yml |
51 | 49 |
|
52 | | -### Devices |
| 50 | +This file is used by the Jenkins build system and documentation generator: |
53 | 51 |
|
54 | | -```yml |
55 | | -param_devices: |
56 | | - - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" } |
57 | | -opt_param_devices: |
58 | | - - { device_path: "/dev/dri", device_host_path: "/dev/dri", desc: "For hardware transcoding" } |
59 | | -``` |
| 52 | +https://docs.linuxserver.io/images/docker-lidarr |
60 | 53 |
|
61 | | -### Environment variables |
| 54 | +--- |
62 | 55 |
|
63 | | -```yml |
64 | | -param_env_vars: |
65 | | - - { env_var: "TZ", env_value: "Europe/London", desc: "Specify a timezone to use EG Europe/London." } |
66 | | -opt_param_env_vars: |
67 | | - - { env_var: "VERSION", env_value: "latest", desc: "Supported values are LATEST, PLEXPASS or a specific version number." } |
68 | | -``` |
| 56 | +### Common README variables |
69 | 57 |
|
70 | | -### Ports |
| 58 | +| Variable | Description | |
| 59 | +|----------|-------------| |
| 60 | +| `project_blurb` | Short description shown under the project logo | |
| 61 | +| `app_setup_block` | Application setup instructions section | |
71 | 62 |
|
72 | | -```yml |
73 | | -param_ports: |
74 | | - - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" } |
75 | | -opt_param_ports: |
76 | | - - { external_port: "80", internal_port: "80", port_desc: "Application WebUI" } |
77 | | -``` |
| 63 | +--- |
78 | 64 |
|
79 | | -### Volumes |
| 65 | +## Container parameters system |
80 | 66 |
|
81 | | -```yml |
82 | | -param_volumes: |
83 | | - - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." } |
84 | | -opt_param_volumes: |
85 | | - - { vol_path: "/config", vol_host_path: "</path/to/appdata/config>", desc: "Configuration files." } |
86 | | -``` |
| 67 | +All Docker run / compose examples are generated automatically. |
87 | 68 |
|
88 | | -### Testing template changes |
| 69 | +Reference variables: |
| 70 | +https://github.com/linuxserver/docker-jenkins-builder/blob/master/vars/_container-vars-blank |
89 | 71 |
|
90 | | -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. |
| 72 | +--- |
91 | 73 |
|
92 | 74 | ## Dockerfiles |
93 | 75 |
|
94 | | -We use multiple Dockerfiles in our repos, this is because sometimes some CPU architectures needs different packages to work. |
95 | | -If you are proposing additional packages to be added, ensure that you added the packages to all the Dockerfiles in alphabetical order. |
| 76 | +We use multiple Dockerfiles because different CPU architectures require different packages. |
| 77 | + |
| 78 | +If you modify dependencies, ensure changes are applied consistently across all Dockerfiles in alphabetical order. |
96 | 79 |
|
97 | | -### Testing your changes |
| 80 | +--- |
| 81 | + |
| 82 | +### Testing your changes locally |
98 | 83 |
|
99 | 84 | ```bash |
100 | 85 | git clone https://github.com/linuxserver/docker-lidarr.git |
101 | 86 | cd docker-lidarr |
| 87 | + |
102 | 88 | docker build \ |
103 | 89 | --no-cache \ |
104 | 90 | --pull \ |
105 | | - -t linuxserver/lidarr:latest . |
106 | | -``` |
107 | | - |
108 | | -The ARM variants can be built on x86_64 hardware and vice versa using `lscr.io/linuxserver/qemu-static` |
109 | | - |
110 | | -```bash |
111 | | -docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset |
112 | | -``` |
113 | | - |
114 | | -Once registered you can define the dockerfile to use with `-f Dockerfile.aarch64`. |
115 | | - |
116 | | -## Update the changelog |
117 | | - |
118 | | -If you are modifying the Dockerfiles or any of the startup scripts in [root](https://github.com/linuxserver/docker-lidarr/tree/master/root), add an entry to the changelog |
119 | | - |
120 | | -```yml |
121 | | -changelogs: |
122 | | - - { date: "DD.MM.YY:", desc: "Added some love to templates" } |
123 | | -``` |
| 91 | + -t linuxserver/lidarr:latest . |
0 commit comments