Merge pull request #3802 from SteveClement/guides

chg: [tools] RHEL7 update status and added gitchangelog to document creation toolchain.

.gitchangelog.rc

@@ -1,3 +1,4 @@
+# -*- coding: utf-8; mode: python -*-
 ##
 ## Format
 ##
@@ -74,6 +75,11 @@ ignore_regexps = [
 ## titles are the label, and a commit is classified under this section if any
 ## of the regexps associated is matching.
 ##
+## Please note that ``section_regexps`` will only classify commits and won't
+## make any changes to the contents. So you'll probably want to go check
+## ``subject_process`` (or ``body_process``) to do some changes to the subject,
+## whenever you are tweaking this variable.
+##
 section_regexps = [
     ('New', [
         r'^[nN]ew\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n]*)$',
@@ -118,6 +124,9 @@ section_regexps = [
 ##
 ##   - strip: remove any spaces before or after the content of the string
 ##
+##   - SetIfEmpty(msg="No commit message."): will set the text to
+##     whatever given ``msg`` if the current text is empty.
+##
 ## Additionally, you can `pipe` the provided filters, for instance:
 #body_process = Wrap(regexp=r'\n(?=\w+\s*:)') | Indent(chars="  ")
 #body_process = Wrap(regexp=r'\n(?=\w+\s*:)')
@@ -133,7 +142,7 @@ body_process = ReSub(r'((^|\n)[A-Z]\w+(-\w+)*: .*(\n\s+.*)*)+$', r'') | strip
 ## Available constructs are those listed in ``body_process`` doc.
 subject_process = (strip |
     ReSub(r'^([cC]hg|[fF]ix|[nN]ew)\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n@]*)(@[a-z]+\s+)*$', r'\4') |
-    ucfirst | final_dot)
+    SetIfEmpty("No commit message.") | ucfirst | final_dot)
 
 
 ## ``tag_filter_regexp`` is a regexp
@@ -143,7 +152,8 @@ subject_process = (strip |
 tag_filter_regexp = r'^v[0-9]+\.[0-9]+\.[0-9]+$'
 
 
-## ``unreleased_version_label`` is a string
+
+## ``unreleased_version_label`` is a string or a callable that outputs a string
 ##
 ## This label will be used as the changelog Title of the last set of changes
 ## between last valid tag and HEAD if any.
@@ -190,3 +200,90 @@ output_engine = rest_py
 ## The default is to include them.
 include_merge = True
 
+
+## ``log_encoding`` is a string identifier
+##
+## This option tells gitchangelog what encoding is outputed by ``git log``.
+## The default is to be clever about it: it checks ``git config`` for
+## ``i18n.logOutputEncoding``, and if not found will default to git's own
+## default: ``utf-8``.
+#log_encoding = 'utf-8'
+
+
+## ``publish`` is a callable
+##
+## Sets what ``gitchangelog`` should do with the output generated by
+## the output engine. ``publish`` is a callable taking one argument
+## that is an interator on lines from the output engine.
+##
+## Some helper callable are provided:
+##
+## Available choices are:
+##
+##   - stdout
+##
+##        Outputs directly to standard output
+##        (This is the default)
+##
+##   - FileInsertAtFirstRegexMatch(file, pattern, idx=lamda m: m.start())
+##
+##        Creates a callable that will parse given file for the given
+##        regex pattern and will insert the output in the file.
+##        ``idx`` is a callable that receive the matching object and
+##        must return a integer index point where to insert the
+##        the output in the file. Default is to return the position of
+##        the start of the matched string.
+##
+##   - FileRegexSubst(file, pattern, replace, flags)
+##
+##        Apply a replace inplace in the given file. Your regex pattern must
+##        take care of everything and might be more complex. Check the README
+##        for a complete copy-pastable example.
+##
+# publish = FileInsertIntoFirstRegexMatch(
+#     "CHANGELOG.rst",
+#     r'/(?P<rev>[0-9]+\.[0-9]+(\.[0-9]+)?)\s+\([0-9]+-[0-9]{2}-[0-9]{2}\)\n--+\n/',
+#     idx=lambda m: m.start(1)
+# )
+#publish = stdout
+
+
+## ``revs`` is a list of callable or a list of string
+##
+## callable will be called to resolve as strings and allow dynamical
+## computation of these. The result will be used as revisions for
+## gitchangelog (as if directly stated on the command line). This allows
+## to filter exaclty which commits will be read by gitchangelog.
+##
+## To get a full documentation on the format of these strings, please
+## refer to the ``git rev-list`` arguments. There are many examples.
+##
+## Using callables is especially useful, for instance, if you
+## are using gitchangelog to generate incrementally your changelog.
+##
+## Some helpers are provided, you can use them::
+##
+##   - FileFirstRegexMatch(file, pattern): will return a callable that will
+##     return the first string match for the given pattern in the given file.
+##     If you use named sub-patterns in your regex pattern, it'll output only
+##     the string matching the regex pattern named "rev".
+##
+##   - Caret(rev): will return the rev prefixed by a "^", which is a
+##     way to remove the given revision and all its ancestor.
+##
+## Please note that if you provide a rev-list on the command line, it'll
+## replace this value (which will then be ignored).
+##
+## If empty, then ``gitchangelog`` will act as it had to generate a full
+## changelog.
+##
+## The default is to use all commits to make the changelog.
+#revs = ["^1.0.3", ]
+#revs = [
+#    Caret(
+#        FileFirstRegexMatch(
+#            "CHANGELOG.rst",
+#            r"(?P<rev>[0-9]+\.[0-9]+(\.[0-9]+)?)\s+\([0-9]+-[0-9]{2}-[0-9]{2}\)\n--+\n")),
+#    "HEAD"
+#]
+revs = []

docs/INSTALL.rhel7.md

@@ -2,6 +2,13 @@
 -------------------------
 
 ## 0/ Overview and Assumptions
+
+{!generic/community.md!}
+
+!!! warning
+    The core MISP team cannot verify if this guide is working or not. Please help us in keeping it up to date and accurate.
+    Thus we also have difficulties in supporting RHEL issues but will do a best effort on a similar yet slightly different setup.
+
 This document details the steps to install MISP on Red Hat Enterprise Linux 7.x (RHEL 7.x). At time of this writing it
 was tested on version 7.5.
 
@@ -18,30 +25,31 @@ The following assumptions with regard to this installation have been made.
 
 ## 1.2/ Configure system hostname
 ```bash
-hostnamectl set-hostname misp # You're choice, in a production environment, it's best to use a FQDN
+sudo hostnamectl set-hostname misp # You're choice, in a production environment, it's best to use a FQDN
 ```
 
 ## 1.3/ Register the system for updates with Red Hat Subscription Manager
 ```bash
-subscription-manager register # register your system to an account
+sudo subscription-manager register --auto-attach # register your system to an account and attach to a current subscription
-subscription-manager attach   # attach your system to a current subscription
 ```
 
 ## 1.4/ Enable the optional, extras and Software Collections (SCL) repos
 ```bash
-subscription-manager repos --enable rhel-7-server-optional-rpms
+sudo subscription-manager refresh 
-subscription-manager repos --enable rhel-7-server-extras-rpms
+sudo subscription-manager repos --enable rhel-7-server-optional-rpms
-subscription-manager repos --enable rhel-server-rhscl-7-rpms
+sudo subscription-manager repos --enable rhel-7-server-extras-rpms
+# This fails on a Trial subscription, it seems.
+##sudo subscription-manager repos --enable rhel-server-rhscl-7-rpms
 ```
 
 ### 1.5a/ OPTIONAL: Install the deltarpm package to help reduce download size when installing updates
 ```bash
-yum install deltarpm
+sudo yum install deltarpm -y
 ```
 
 ## 1.5/ Update the system and reboot
 ```bash
-yum update
+yum update -y
 ```
 
 !!! note
@@ -53,7 +61,7 @@ yum update
 
 ## 1.6/ Install the EPEL repo
 ```bash
-yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm -y
 ```
 
 ## 1.7/ Install the SCL repo

docs/xINSTALL.rhel7.md

@@ -2,8 +2,17 @@
 -------------------------
 
 ## 0/ Overview and Assumptions
-This document details the steps to install MISP on Red Hat Enterprise Linux 7.x BETA (RHEL 7.x). At time of this writing it
+
-was tested on version 7.6 BETA.
+{!generic/community.md!}
+
+!!! warning
+    The core MISP team cannot verify if this guide is working or not. Please help us in keeping it up to date and accurate.
+    Thus we also have difficulties in supporting RHEL issues but will do a best effort on a similar yet slightly different setup.
+
+!!! warning
+    This is a carbon copy of the 7.5 document. Please try to adapt it to the 7.6 BETA release so we can seamlessly switch versions once it is not BETA anymore.
+
+This document details the steps to install MISP on Red Hat Enterprise Linux 7.x BETA (RHEL 7.x). At time of this writing it could be tested on version 7.6 BETA.
 
 The following assumptions with regard to this installation have been made.
 
@@ -31,47 +40,47 @@ The following assumptions with regard to this installation have been made.
 
 ## 1.2/ Configure system hostname
 ```bash
-hostnamectl set-hostname misp # You're choice, in a production environment, it's best to use a FQDN
+sudo hostnamectl set-hostname misp # Your choice, in a production environment, it's best to use a FQDN
 ```
 
 ## 1.3/ Register the system for updates with Red Hat Subscription Manager
 ```bash
-subscription-manager register # register your system to an account
+sudo subscription-manager register # register your system to an account
-subscription-manager attach   # attach your system to a current subscription
+sudo subscription-manager attach   # attach your system to a current subscription
 ```
 
 ## 1.4/ Enable the optional, extras and Software Collections (SCL) repos
 ```bash
-subscription-manager repos --enable rhel-7-server-optional-rpms
+sudo subscription-manager repos --enable rhel-7-server-optional-rpms
-subscription-manager repos --enable rhel-7-server-extras-rpms
+sudo subscription-manager repos --enable rhel-7-server-extras-rpms
-subscription-manager repos --enable rhel-server-rhscl-7-rpms
+sudo subscription-manager repos --enable rhel-server-rhscl-7-rpms
 ```
 
 ### 1.5a/ OPTIONAL: Install the deltarpm package to help reduce download size when installing updates
 ```bash
-yum install deltarpm
+sudo yum install deltarpm -y
 ```
 
 ## 1.5/ Update the system and reboot
 ```bash
-yum update
+sudo yum update -y
 ```
 
 !!! note
-    As time of writing performing a yum update results in the rhel-7-server-rt-beta-rpms being forbidden.<br />
+    At the time of writing performing a yum update results in the rhel-7-server-rt-beta-rpms being forbidden.<br />
     The repo can be disabled using the following command
     ```bash
-    subscription-manager repos --disable rhel-7-server-rt-beta-rpms
+    sudo subscription-manager repos --disable rhel-7-server-rt-beta-rpms
     ```
 
 ## 1.6/ Install the EPEL repo
 ```bash
-yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm -y
 ```
 
 ## 1.7/ Install the SCL repo
 ```bash
-yum install centos-release-scl
+sudo yum install centos-release-scl -y
 ```
 
 # 2/ Install Dependencies
@@ -79,18 +88,18 @@ Once the system is installed and updated, the following steps can be performed a
 
 ## 2.01/ Install some base system dependencies
 ```bash
-yum install gcc git httpd zip python-devel libxslt-devel zlib-devel python-pip ssdeep-devel
+sudo yum install gcc git httpd zip python-devel libxslt-devel zlib-devel python-pip ssdeep-devel -y
 ```
 
 ## 2.02/ Install MariaDB 10.2 from SCL
 ```bash
-yum install rh-mariadb102
+sudo yum install rh-mariadb102 -y
 ```
 
 ## 2.03/ Start the MariaDB service and enable it to start on boot
 ```bash
-systemctl start rh-mariadb102-mariadb.service
+sudo systemctl start rh-mariadb102-mariadb.service
-systemctl enable rh-mariadb102-mariadb.service
+sudo systemctl enable rh-mariadb102-mariadb.service
 ```
 
 !!! note
@@ -102,7 +111,7 @@ systemctl enable rh-mariadb102-mariadb.service
 
 ## 2.04/ Install PHP 7.1 from SCL
 ```bash
-yum install rh-php71 rh-php71-php-fpm rh-php71-php-devel rh-php71-php-mysqlnd rh-php71-php-mbstring rh-php71-php-xml rh-php71-php-bcmath rh-php71-php-opcache
+sudo yum install rh-php71 rh-php71-php-fpm rh-php71-php-devel rh-php71-php-mysqlnd rh-php71-php-mbstring rh-php71-php-xml rh-php71-php-bcmath rh-php71-php-opcache -y
 ```
 
 !!! note

tools/gen_misp_install_docs.sh

@@ -12,7 +12,7 @@ fi
 
 if [ -z "$VIRTUAL_ENV" ]; then
     virtualenv -p python3 mkdocs
-    ${PWD}/mkdocs/bin/pip install mkdocs mkdocs-material markdown-include python-markdown-comments
+    ${PWD}/mkdocs/bin/pip install mkdocs mkdocs-material markdown-include python-markdown-comments gitchangelog
 fi
 
 wget -O ../docs/Changelog.md https://www.misp-project.org/Changelog.txt