1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
# Contributing to Shoutrrr
Original Repository:
<https://github.com/containrrr/shoutrrr>
Fork Repository:
<https://github.com/nicholas-fedor/shoutrrr>
## Getting Started
### Cloning the Repository
```bash
git clone https://github.com/nicholas-fedor/shoutrrr.git
```
### Development Tools
- [Make](https://www.gnu.org/software/make/)
- Windows
```powershell
winget install --id GnuWin32.Make
```
- Linux
Ubuntu/Debian:
```bash
sudo apt install make -y
```
Fedora/RHEL:
```bash
sudo dnf install make
```
Arch:
```bash
sudo pacman -S make
```
- macOS
```bash
brew install make
```
- [Go](https://go.dev/)
Installation Documentation: <https://go.dev/doc/install>
- [Golangci-Lint](https://golangci-lint.run/)
Installation Documentation: <https://golangci-lint.run/welcome/install/#local-installation>
- [GoReleaser](https://goreleaser.com/)
Installation Documentation: <https://goreleaser.com/install/>
- [MkDocs](https://www.mkdocs.org/)
Installation Documentation: <https://www.mkdocs.org/user-guide/installation/>
1. Confirm that you have Python and Pip installed:
```bash
python --version
pip --version
```
2. Install MkDocs:
```bash
pip install mkdocs
```
3. Install Shoutrrr's dependencies:
```bash
pip install -r build/mkdocs/docs-requirements.txt
```
## Building and Testing
Shoutrrr is a Go library and is built with Go commands.
The following commands assume that you are at the root level of your repo.
```bash
./build/build.sh # compiles and packages a stand-alone executable
go test ./... -v # runs tests with verbose output
./shoutrrr/shoutrrr # runs the application
```
## Documentation
Shoutrrr's documentation is provided via a GitHub Pages static website.
MkDocs is used to generate the files, via the `./github/workflows/publish-docs.yaml` GitHub workflow, which are deployed to the root directory of the `gh-pages` branch.
GitHub automatically deploys the website upon changes to the `gh-pages` branch.
### Local Development
Ensure that you have first installed the necessary dependencies.
To run the website locally, run the following from the root directory:
```bash
mkdocs serve --config-file build/mkdocs/mkdocs.yaml
```
Note: Disable the markdown extension pymdownx.snippets > check_paths option if not generating the service config docs via the `scripts\generate-service-config-docs.sh` script.
## Semantic Branch Names
Shoutrrr uses semantic branch naming for structured branch names.
| Type | Description | Examples |
|------------|--------------------------------------------------------------------|------------------------------|
| `chore` | updating grunt tasks etc; no production code change | `chore/update-build-script` |
| `docs` | changes to the documentation | `docs/update-readme` |
| `feat` | new feature for the user, not a new feature for build script | `feat/user-authentication` |
| `fix` | bug fix for the user, not a fix to a build script | `fix/login-error` |
| `refactor` | refactoring production code, eg. renaming a variable | `refactor/rename-user-class` |
| `style` | formatting, missing semi colons, etc; no production code change | `style/format-components` |
| `test` | adding missing tests, refactoring tests; no production code change | `test/add-unit-tests` |
- If the branch is addressing an issue, then include the issue number in the branch name:
```text
feat/#160-add-wechat-support
```
## Conventional Commit Messages
Shoutrrr uses the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary) for structured commit messages.
Commit Message Structure:
```text
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
|
