Merge pull request #4235 from laf/changelog-automation

documentation: Added docs + file changes to support creating new releases/changelog

composer.json

@@ -3,6 +3,7 @@
         "squizlabs/php_codesniffer": "*",
         "phpunit/phpunit": "4.*",
         "jakub-onderka/php-parallel-lint": "*",
-        "jakub-onderka/php-console-highlighter": "*"
+        "jakub-onderka/php-console-highlighter": "*",
+        "fojuth/readmegen": "1.*"
     }
 }

doc/Developing/Creating-Release.md

@@ -0,0 +1,28 @@
+Developing/Creating-Release.md
+# Creating a release
+
+### GitHub
+You can create a new release on [GitHub](https://github.com/librenms/librenms/releases/new).
+
+Enter the tag version that month, i.e for September 2016 you would enter `201609`.
+
+Enter a title, we usually use `August 2016 Release`
+
+Enter a placeholder for the body, we will edit this later.
+
+### Create changelog
+We utilise [Readmegen](https://github.com/fojuth/readmegen) to automatically populate the Changelog.
+
+Install `readmegen` using `composer`:
+
+```bash
+./composer.phar update
+```
+
+You can now create the update change log by running (201608 was our last release):
+
+```bash
+./vendor/bin/readmegen --from 201608 --release 201609
+```
+
+Now commit and push the change that has been made to `doc\General\Changelog.md`

doc/Developing/Merging-Pull-Requests.md

@@ -0,0 +1,27 @@
+Developing/Merging-Pull-Requests.md
+# Merging Pull Requests
+
+### GitHub
+We will now build the monthly change log from our GitHub commits. When merging a commit, please 
+ensure you:
+
+  - Click the `Merge pull request` button
+  - Give the merge a descriptive but short title
+  - For the commit message prepend it with one of the following tags for the pull request to appear in the changelog:
+    - devices: or newdevice: For new device support.
+    - feature: or feat: To indicate this is a new or updated feature
+    - webui: or web: To indicate this is an update to the WebUI
+    - fix: or bugfix: To show this is a bug fix.
+    - refactoring: or refactor: When the changes are refactoring a large portion of code
+  - You can reference an issue number with `#xyz`, i.e `#1234`
+  - Use the `Confirm squash and merge` button to merge.
+
+### Example commits
+
+#### Feature
+
+feature: Added new availability map #4401
+
+#### New device
+
+newdevice: Added support for Cisco ASA #4402

doc/General/Releases.md

@@ -0,0 +1,16 @@
+source: General/Releases.md
+# LibreNMS Releases
+
+We try to ensure that breaking changes aren't introduced by utilising various automated 
+code testing, syntax testing and unit testing along with manual code review. However 
+bugs can and do get introduced as well as major refactoring to improve the quality of 
+the code base.
+
+With this in mind, we provide a monthly stable release which is released on or around 
+the last Sunday of the month. Code pull requests (aside from Bug fixes) are stopped days 
+leading up to the release to ensure that we have a clean working branch at that point.
+
+The releases are titled after that month in the format `YYYYMM`, i.e `201608`. The 
+Changelog is also updated and will reference the release number and date so you can see 
+what changes have been made since the last release.
+

mkdocs.yml

@@ -32,6 +32,7 @@ pages:
     - General/Contributing.md
     - General/Credits.md
     - General/Updating.md
+    - General/Releases.md
     - General/Welcome-to-Observium-users.md
 - Extensions:
     - Extensions/Alerting.md
@@ -72,6 +73,8 @@ pages:
     - Developing/Code-Guidelines.md
     - Developing/Code-Structure.md
     - Developing/Creating-Documentation.md
+    - Developing/Merging-Pull-Requests.md
+    - Developing/Creating-Release.md
     - Developing/Dynamic-Config.md
     - Developing/Sensor-State-Support.md
     - Developing/Style-Guidelines.md

readmegen.yml

@@ -0,0 +1,25 @@
+vcs: git
+format: md
+issue_tracker_pattern: https://github.com/librenms/librenms/issues/\1
+break: "## Changelog"
+output_file_name: "doc/General/Changelog.md"
+message_groups:
+  Bugfixes:
+    - fix
+    - bugfix
+  Devices:
+    - devices
+    - newdevice
+  WebUI:
+    - webui
+    - web
+  Features:
+    - feature
+    - feat
+  Documentation:
+    - docs
+    - doc
+    - documentation
+  Refactoring:
+    - refactoring
+    - refactor