Commit 03f45944 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'feat/use-minor-version-alias' into 'master' 

Use minor version alias

Closes #16

See merge request to-be-continuous/doc!21
parents fff28da0 7a8ede16

README.md

+24 −0
Original line number Diff line number Diff line
@@ -22,8 +22,32 @@ It can be configured with the following variables: 


* `GITLAB_TOKEN`: a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with scopes `api,read_repository`

  and at least `Developer` role on all groups & projects to crawl (not required if only `public` groups and projects),

* `PREF_TAG_PATTERN`: preferred tag pattern.

* `KICKER_RESOURCE_GROUPS`: JSON configuration of GitLab groups to crawl.



### Details about `PREF_TAG_PATTERN`



The algorithm to determine which template latest version to include in Kicker is the following:



1. get all published (Git) tags, 

2. sort them (using [Version sort](https://www.gnu.org/software/coreutils/manual/html_node/Version-sort-overview.html)),

3. among this list, filter all tags matching a _preferred pattern_ (regex)

    * one or more matches: return the latest one from the filtered list

    * none matches (fallback): simply pick the latest one from the unfiltered list



The `PREF_TAG_PATTERN` variable allows to define the preferred version pattern to be used as the latest version to include in Kicker.



By default it is set as `^v?[0-9]+\.[0-9]+$`. In other words, Kicker will propose the latest published 

minor version alias (ex `2.4`), when present.



If your want another behavior in your self-managed GitLab, simply override this variable in your local copy 

of the `to-be-continuous/doc` project. Example values:



* full semver version (incuding fix part): `^v?[0-9]+\.[0-9]+\.[0-9]+$`

* simply the latest tag (whichever the format): `.*`



### Details about `KICKER_RESOURCE_GROUPS`



Here is an example of `KICKER_RESOURCE_GROUPS` content:



```json

kicker-aggregated.json

0 → 100644
+1 −0

File added.

Preview size limit exceeded, changes collapsed.

process-templates.sh

+32 −19
Original line number Diff line number Diff line
@@ -54,13 +54,17 @@ function maybe_process_template() { 
  project_name=$(echo "$project_json" | jq -r .path)

  project_path=$(echo "$project_json" | jq -r .path_with_namespace)



  # get latest tag

  tag=$(curl -sSf -H "$AUTH_HEADER" "$API_URL/projects/$project_id/repository/tags?per_page=1" | jq -r '.[0].name')

  # get tags (latest first, oldest last)

  all_tags=$(curl -sSf -H "$AUTH_HEADER" "$API_URL/projects/$project_id/repository/tags?per_page=100" | jq -r '.[].name' | sort -rV)

  # filter tags matching preferred pattern, or all tags if none matches

  matching_tags=$(echo "$all_tags" | grep -E "$PREF_TAG_PATTERN" || echo "$all_tags")

  tag=$(echo "$matching_tags" | head -n 1)

  if [[ -n "$tag" ]] && [[ "$tag" != "null" ]]

  then

    project_path_enc=${project_path//\//%2f}

    web_url=$(echo "$project_json" | jq -r .web_url)

    add_info_json="{extension_id: $extension_json, project: {tag: \"$tag\", name: \"$project_name\", path: \"$project_path\", web_url: \"$web_url\"}}"

    tags_array_json=$(echo "$all_tags" | jq --raw-input . | jq --slurp --compact-output .)

    add_info_json="{extension_id: $extension_json, project: {tag: \"$tag\", tags: $tags_array_json, name: \"$project_name\", path: \"$project_path\", web_url: \"$web_url\"}}"



    # get kicker.json file from latest tag

    if template_json=$(curl -sf -H "$AUTH_HEADER" "$API_URL/projects/$project_id/repository/files/kicker.json/raw?ref=$tag")
@@ -179,7 +183,7 @@ function build_aggregated_json() { 
    if [[ -d "$tmpl_dir/variants" ]]

    then

      log_info " ... adding outer variants to \\e[33;1m${tmpl_file}\\e[0m"

      variants_array_json=$(jq -s '.' $tmpl_dir/variants/*.json)

      variants_array_json=$(jq --slurp '.' $tmpl_dir/variants/*.json)

      jq ".variants+=$variants_array_json" < "$tmpl_file" > "$tmpl_dir/template-final.json"

    else

      cp "$tmpl_file" "$tmpl_dir/template-final.json"
@@ -190,51 +194,50 @@ function build_aggregated_json() { 
  if [[ -d "$tmp_dir/presets" ]]

  then

  log_info "--- Assembling presets..."

    presets_array_json=$(jq -s '.' $tmp_dir/presets/*.json)

    presets_array_json=$(jq --slurp '.' $tmp_dir/presets/*.json)

  else

    presets_array_json='[]'

  fi



  # 3: assemble

  jq -s '.' ${tmp_dir}/*/template-final.json | jq "{extensions: $extensions_array_json, presets: $presets_array_json, templates: .}" > "$JSON_OUT"

  jq --slurp '.' ${tmp_dir}/*/template-final.json | jq --compact-output "{extensions: $extensions_array_json, presets: $presets_array_json, templates: .}" > "$JSON_OUT"

}



function build_aggregated_toc() {

  log_info "--- Generating aggregated documentation TOC..."

  toc_file="$tmp_dir/toc.md"



  {

    echo "- Templates Reference:"

    if [[ -f "$tmp_dir/toc/build" ]]; then

      echo "  - Build & Test:"

      sort "$tmp_dir/toc/build" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/build" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/analyse" ]]; then

      echo "  - Code Analysis:"

      sort "$tmp_dir/toc/analyse" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/analyse" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/package" ]]; then

      echo "  - Packaging:"

      sort "$tmp_dir/toc/package" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/package" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/infrastructure" ]]; then

      echo "  - Infrastructure:"

      sort "$tmp_dir/toc/infrastructure" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/infrastructure" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/hosting" ]]; then

      echo "  - Deploy & Run:"

      sort "$tmp_dir/toc/hosting" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/hosting" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/acceptance" ]]; then

      echo "  - Acceptance:"

      sort "$tmp_dir/toc/acceptance" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/acceptance" | sed 's/^/    /'

    fi

    if [[ -f "$tmp_dir/toc/others" ]]; then

      echo "  - Others:"

      sort "$tmp_dir/toc/others" | sed 's/^/    /'

      sort -f "$tmp_dir/toc/others" | sed 's/^/    /'

    fi

  } > "$toc_file"



  cat "$toc_file"

}



# API url default to local GitLab instance
@@ -244,6 +247,9 @@ DOC_OUT=./docs 


KICKER_RESOURCE_GROUPS=${KICKER_RESOURCE_GROUPS:-'[{"path": "to-be-continuous", "visibility": "public"}]'}



# preferred tag pattern to include: minor version alias by default (X.Y)

PREF_TAG_PATTERN='^v?[0-9]+\.[0-9]+$'



log_info parse params



# parse arguments
@@ -258,6 +264,7 @@ case $key in 
    log_info "       [--json-out <output JSON file>]"

    log_info "       [--doc-out <README output dir>]"

    log_info "       [--groups <JSON encoded GitLab groups to crawl>]"

    log_info "       [--tag-pattern <preferred tag pattern (regex)>]"

    echo

    log_info "Groups to crawl shall be formatted as follows:"

    log_info "[
@@ -312,6 +319,11 @@ case $key in 
    shift # past argument

    shift # past value

    ;;

    --tag-pattern)

    PREF_TAG_PATTERN="$2"

    shift # past argument

    shift # past value

    ;;

    *) # unknown option

    POSITIONAL+=("$1") # save it in an array for later

    shift # past argument
@@ -328,6 +340,7 @@ log_info "- GitLab API url (--api) : \\e[33;1m${API_URL}\\e[0m" 
log_info "- kicker output file (--json-out)  : \\e[33;1m${JSON_OUT}\\e[0m"

log_info "- readme output dir  (--doc-out)   : \\e[33;1m${DOC_OUT}\\e[0m"

log_info "- groups to process  (--groups)    : \\e[33;1m${KICKER_RESOURCE_GROUPS}\\e[0m"

log_info "- pref. tag pattern (--tag-pattern): \\e[33;1m${PREF_TAG_PATTERN}\\e[0m"



# create a temporary directory to download individual kicker files

tmp_dir=$(mktemp -d)