sync development docs and boilerplate with sap_host_exporter

.ci/gh_release_to_obs_changeset.py

@@ -2,9 +2,10 @@
 
 import argparse
 import json
+import os
 import sys
 import textwrap
-from urllib import request
+import urllib.request
 import urllib.error
 from datetime import datetime
 from datetime import timezone
@@ -25,9 +26,18 @@
 releaseSegment = f"/tags/{args.tag}" if args.tag else "/latest"
 url = f'https://api.github.com/repos/{args.repo}/releases{releaseSegment}'
 
+request = urllib.request.Request(url)
+
+githubToken = os.getenv("GITHUB_OAUTH_TOKEN")
+if githubToken:
+    request.add_header("Authorization", "token " + githubToken)
+
 try:
-    response = request.urlopen(url)
+    response = urllib.request.urlopen(request)
 except urllib.error.HTTPError as error:
+    if error.code == 404:
+        print(f"Release {args.tag} not found in {args.repo}. Skipping changelog generation.")
+        sys.exit(0)
     print(f"GitHub API responded with a {error.code} error!", file=sys.stderr)
     print("Url:", url, file=sys.stderr)
     print("Response:", json.dumps(json.load(error), indent=4), file=sys.stderr, sep="\n")

Makefile

@@ -1,6 +1,6 @@
 # this is the what ends up in the RPM "Version" field and it is also used as suffix for the built binaries
-# it can be arbitrary for local builds, but it if you want to commit to OBS it must correspond to a Git tag with an associated GitHub release
-VERSION ?= dev
+# if you want to commit to OBS it must be a remotely available Git reference
+VERSION ?= $(shell git rev-parse --short HEAD)
 
 # we only use this to comply with RPM changelog conventions at SUSE
 AUTHOR ?= shap-staff@suse.de
@@ -13,7 +13,7 @@ REPOSITORY ?= clusterlabs/ha_cluster_exporter
 # the Go archs we crosscompile to
 ARCHS ?= amd64 arm64 ppc64le s390x
 
-default: clean mod-tidy fmt vet-check test build
+default: clean download mod-tidy fmt vet-check test build
 
 download:
 	go mod download
@@ -47,32 +47,34 @@ fmt-check:
 test: download
 	go test -v ./...
 
-coverage: coverage.out
-coverage.out:
-	go test -cover -coverprofile=coverage.out ./...
-	go tool cover -html=coverage.out
+coverage:
+	@mkdir build
+	go test -cover -coverprofile=build/coverage ./...
+	go tool cover -html=build/coverage
 
 clean: clean-bin clean-obs
 	go clean
-	rm -f coverage.out
+	rm -rf build
 
 clean-bin:
 	rm -rf build/bin
 
 clean-obs:
 	rm -rf build/obs
 
-obs-workdir: build/obs
-build/obs:
-	osc checkout $(OBS_PROJECT)/$(OBS_PACKAGE) -o build/obs
+obs-workdir: clean-obs
+	@mkdir -p build/obs
+	osc checkout $(OBS_PROJECT) $(OBS_PACKAGE) -o build/obs
 	rm -f build/obs/*.tar.gz
 	cp -rv packaging/obs/* build/obs/
-	sed -i 's/%%VERSION%%/$(VERSION)/' build/obs/_service
+# we interpolate environment variables in OBS _service file so that we control what is downloaded by the tar_scm source service
+	sed -i 's~%%VERSION%%~$(VERSION)~' build/obs/_service
+	sed -i 's~%%REPOSITORY%%~$(REPOSITORY)~' build/obs/_service
 	cd build/obs; osc service runall
 	.ci/gh_release_to_obs_changeset.py $(REPOSITORY) -a $(AUTHOR) -t $(VERSION) -f build/obs/$(OBS_PACKAGE).changes || true
 
 obs-commit: obs-workdir
 	cd build/obs; osc addremove
-	cd build/obs; osc commit -m "Automated $(VERSION) release"
+	cd build/obs; osc commit -m "Update to git ref $(VERSION)"
 
-.PHONY: default download install static-checks vet-check fmt fmt-check mod-tidy test clean clean-bin clean-obs build build-all obs-commit obs-workdir $(ARCHS)
+.PHONY: default download install static-checks vet-check fmt fmt-check mod-tidy test coverage clean clean-bin clean-obs build build-all obs-commit obs-workdir $(ARCHS)

README.md

@@ -8,7 +8,10 @@ This is a bespoke Prometheus exporter used to enable the monitoring of Pacemaker
 1. [Features](#features)
 2. [Installation](#installation)
 3. [Usage](#usage)
-4. [Development](#development)
+   1. [Metrics](doc/metrics.md)
+5. [Contributing](#contributing)
+   1. [Design](doc/design.md)
+   2. [Development](doc/development.md)
 5. [License](#license)
 
 ## Features
@@ -32,7 +35,6 @@ The project can be installed in many ways, including but not limited to:
 2. [Go](#go)
 3. [RPM](#rpm)
 
-
 ### Manual clone & build
 
 ```
@@ -73,6 +75,8 @@ It will export the metrics under the `/metrics` path, on port `9664` by default.
 While the exporter can run outside a HA cluster node, it won't export any metric it can't collect; e.g. it won't export DRBD metrics if it can't be locally inspected with `drbdsetup`.  
 A warning message will inform the user of such cases.
 
+Please, refer to [doc/metrics.md](doc/metrics.md) for extensive details about all the exported metrics.
+
 **Hint:**
 You can deploy a full HA Cluster via Terraform with [SUSE/ha-sap-terraform-deployments](https://github.com/SUSE/ha-sap-terraform-deployments).
 
@@ -102,30 +106,7 @@ systemctl --now enable prometheus-ha_cluster_exporter
 
 Pull requests are more than welcome!
 
-We recommend having a look at the [design document](doc/design.md) before contributing.
-
-#### Makefile
-
-Most development tasks can be accomplished via [make](Makefile).
-
-The default target will clean, analyse, test and build the amd64 binary into the `build/bin` directory.
-
-You can also cross-compile to the various architectures we support with `make build-all`.
-
-##### Open Build Service releases
-
-The CI will automatically publish GitHub releases to SUSE's Open Build Service: to perform a new release, just publish a new GH release or push a git tag. Tags must always follow the [SemVer](https://semver.org/) scheme.
-
-If you wish to produce an OBS working directory locally, after you have configured [`osc`](https://en.opensuse.org/openSUSE:OSC) locally, you can run: 
-```
-make obs-workdir
-```
-This will checkout the OBS project and prepare a release in the `build/obs` directory.
-
-Note that, by default, `dev` is used as the RPM `Version` field, as well as a suffix for all the binary file names.  
-To prepare an actual release, you can use the `VERSION` environment variable to set this value to an actual release tag.
-
-To commit the release to OBS, run `make obs-commit`.
+We recommend having a look at the [design document](doc/design.md) and the [development notes](doc/development.md) before contributing.
 
 ## License
 

doc/development.md

@@ -0,0 +1,43 @@
+# Developer notes
+
+1. [Makefile](#makefile)
+2. [OBS packaging](#obs-packaging)
+
+
+## Makefile
+
+Most development tasks can be accomplished via [make](../Makefile).
+
+For starters, you can run the default target with just `make`.
+
+The default target will clean, analyse, test and build the amd64 binary into the `build/bin` directory.
+
+You can also cross-compile to the various architectures we support with `make build-all`.
+
+
+## OBS Packaging
+
+The CI will automatically publish GitHub releases to SUSE's Open Build Service: to perform a new release, just publish a new GH release or push a git tag. Tags must always follow the [SemVer](https://semver.org/) scheme.
+
+If you wish to produce an OBS working directory locally, having configured [`osc`](https://en.opensuse.org/openSUSE:OSC) already, you can run:
+```
+make obs-workdir
+```
+This will checkout the OBS project and prepare a new OBS commit in the `build/obs` directory.
+
+Note that, by default, the current Git working directory HEAD reference is used to download the sources from the remote, so this reference must have been pushed beforehand.
+
+You can use the `OSB_PROJECT`, `OBS_PACKAGE`, `REPOSITORY` and `VERSION` environment variables to change the behaviour of OBS-related make targets.
+
+For example, if you were on a feature branch of your own fork, you may want to change these variables, so:
+```bash
+git push feature/yxz # don't forget to make changes remotely available
+export OBS_PROJECT=home:JohnDoe
+export OBS_PACKAGE=my_project_branch
+export REPOSITORY=johndoe/my_forked_repo
+export VERSION=feature/yxz
+make obs-workdir
+``` 
+will prepare to commit on OBS into `home:JohnDoe/my_project_branch` by checking out the branch `feature/yxz` from `github.com/johndoe/my_forked_repo`.
+
+At last, to actually perform the commit into OBS, run `make obs-commit`. 

packaging/obs/_service

@@ -1,15 +1,14 @@
 <services>
     <service name="tar_scm" mode="disabled">
-        <param name="url">git://github.com/ClusterLabs/ha_cluster_exporter.git</param>
+        <param name="url">git://github.com/%%REPOSITORY%%.git</param>
         <param name="scm">git</param>
         <param name="revision">%%VERSION%%</param>
         <param name="exclude">.git</param>
-        <param name="versionformat">@PARENT_TAG@</param>
-        <param name="filename">prometheus-ha_cluster_exporter</param>
+        <param name="versionformat">@PARENT_TAG@+git.%ct.%h</param>
+        <param name="filename">prometheus-sap_host_exporter</param>
     </service>
     <service name="set_version" mode="disabled">
-        <param name="version">%%VERSION%%</param>
-        <param name="file">prometheus-ha_cluster_exporter.spec</param>
+        <param name="file">prometheus-sap_host_exporter.spec</param>
     </service>
     <service name="recompress" mode="disabled">
         <param name="file">*.tar</param>