Snapshotizr

Snapshot creates a diff for each project modified by your team members on Github.

Slack channel: #STP-Snapshotizr

Setup

Install and initialise snapshotizr:

npm install -g snapshotizr
snapshotizr-init

Create a github token with scope: repo and edit configuration file: ~/snapshotizr/config.js.

Enjoy! :)

FTP upload

If you want snapshotizr to automatically upload generated diffs (aka. reports) to your FTP server, please provide "ftp" object with following fields to the config file:

ftp: {
  host: '192.168.x.x',
  user: 'username',
  remoteRoot: '/public_dir/some_subdir/'
}

Password is not required in the config file - if nothing given, you'll be prompted for it during execution time.

AI generated summary

As we are required to create our work summary in Polish, let's use AI for that.

OpenAI has been implemented as the service of choice, so in order to use the integration you have to obtain the token. Please refer the docs to find out how to get one: https://help.openai.com/en/

Configuration is described in the example config file. If you already had a config created, you have to copy & paste it from the example file located in the source code of this project - global node_modules/snapshotizr/examples/config.js.

Here is the default config at the time of adding the feature, but it might be out of date, because docs like to be out of date 😉

openai: {
    enabled: false,
    apiKey: '', // Needed to use OpenAI API

    // systemQueryPreset: 'perProject', // pick one of the predefined system queries. See src/openai.js for details

    // Add an additional part in the system query in between the format description and the system query preset.
    // It can be used so the model understands common phrases like `pulse tracking`.
    // systemQueryAddon: '`Pulse` is the user behavior tracking system used in the company.',

    // Override the system query. Will not use any of the default system queries or git log format description. Make it on your own.
    // customSystemQuery: null, // provide your own system query. Takes precedence over systemQueryPreset

    // streamOutput: true, // Print in chunks as they arrive or print all at once
    // printInput: true, // Print git logs input to the console

    // Completions parameters - see https://platform.openai.com/docs/api-reference/completions/create
    // You can add here anythig from the API reference.
    // Model is required. Other are defaults listed here to point you to the possibilities.
    // Do not set `response_format` here, it is set in the code. Same for `stream`.
    completions: {
        model: 'gpt-4o',
        // max_completion_tokens: 2048,
        // temperature: 1,
        // top_p: 1,
        // frequency_penalty: 0,
        // presence_penalty: 0,
    },
},

The generated summary is in markdown format, but Jira does not handle pasting md. In order to paste it as the formatted text you have to format it with something like https://markdowntohtml.com/

Slack notifications

If you want to receive success and failure notifications on Slack, please provide a "slack" object with following fields in the config file:

slack: {
  enabled: true,
  token: 'SLACK_TOKEN',
  channel: 'CHANNEL_ID',
},

You need to create a Slack application to get the token needed here. Creating a Slack app in the sch-chat workspace requires admin approval, but is easy to get. I suggest having a single Slack app per team and just re-use it for all integrations. Scope required here is chat:write (you need to add the app to your channel first).

To get a channel ID it's easiest to open Slack in the browser, enter the desired channel and pick its ID from URL e.g. https://app.slack.com/client/T0356Q2CJ/C044Q8M5W <-- C044Q8M5W is the channel ID.

Working directory

Default

Snapshotizr uses directory: ~/snapshotizr/.

Custom

You can use file ~/.snapshotizr for configuration and also add there key 'appDir' in root with appropriate path to define working directory (for repositories and reports)

Usage

Just run:

snapshotizr -h

to see available options:

  -f, --from from       Date string or keyword `last`, default value: start of this month. `last`
                        will be replaced with the last report date based on the directory creation
                        date
  -u, --until until     Date string, default value: now
  -s, --skip-cleanup    Do not remove cloned repositories at the end of the script
  -c, --config string   Configuration file path
  -h, --help            Print this help message

Example - generate report since 2021-01-25 up to now:

snapshotizr --from 2021-01-25

Or detect automatically the last report date with:

snapshotizr --from last

Limitations

Supported protocols

This tool support only HTTPS protocol to work with Git.

Limited number of public events in GHE

Github provides only last 100 public events performed by a user (event == push, not commit). So in the specific situation, you can lose some repos.

To work around that you can explicitly specify repos inside config.profiles in configuration file, for example:

const config = { 
  appDir: '',
  skipCleanup: true,
  profiles: [
    {   
      name: 'ghe',
      repos: ['snt/fastenposten', 'snt/snt-capi-preview'],
      ...

it is also possible to exclude specific repositories from processing:

const config = { 
  appDir: '',
  skipCleanup: true,
  profiles: [
    {   
      name: 'ghe',
      reposToSkip: ['spt-privacy/jakub-test', 'spt/adventofcode' ],
      ...

Generating report for Jira

Besides storing a code snapshot we're all required to create Jira issues inside 'Copyright' project with a human-readable report listing all work delivered this month present in the snapshot (in Polish).

See AI generated summary for the smarter way. If you do not want to pay a few cents, or you do not trust AI, try the following approach.

Here's a snippet to make this work easier. It takes your push messages and translates them using Google Translate. I highly suggest going through it afterwards, there are often beauties in there e.g. 'fix lint' ==> 'napraw kłaczki' 😂 Still, it's faster and more detailed than writing it from scratch.

npm i -g git-standup google-translate-cli
git standup -m 3 -A "`date +%Y-%m-01` 00:00:00" -D short -s | grep '<IMIE_NAZWISKO>' | cut -f3- -d" " | rev | cut -d" " -f4- | rev | translate -s en -t pl

• replace date param with a proper date matching from param set for snapshotizr, e.g. git standup -m 3 -A "2021-01-25 00:00:00" ...
• adjust git standup params to fit the way you have your projects stored locally.
• <IMIE_NAZWISKO> is spelled normally e.g. 'Wojciech Iskra'

How to publish package to NpmJS

Package is published to NpmJS when NPM tag is created.

You can bump version using command npm version.

Example:

npm version patch
npm version minor
npm version major

When new version will be created code need to pushed to master:

git push --tags