Development guidelines

Back to main page

Please read the Development section of official documentation before contributing any code into this project. This wiki page now focuses only on the guidelines regarding submitting issues and related workflow.

Submitting issues

  • For new issues use english language
  • Fill in as many issue meta information as possible
  • Use issue references in Git commits to assign them to appropriate issues

Issue workflow

  • Current workflow requires either email notifications to be turned on, or frequent checking of the Redmine interface.
  • Assignee owns the issue and it is the person that is currently supposed to work on that.
  • When attention of another person is required
    • ensure the needed person(nel) is among watchers, preferably change state to Feedback and explain the need in comment
    • asked person can decide to take over the issue as the owner (for example in case of substantial contribution, to keep track of his work, or just to be bugged) and later return it to the original owner
  • When the issue is resolved, change status to Resolved
  • When the issue is pushed to staging server (mentat-dev), change status to In Review
  • Closed or Rejected only on apparent team consensus or on approval of project manager
  • Issue priority has roughly following meaning:
    • low - can be dealt with at proper time (nothing important depends on this, nice to have)
    • normal - usual code churn
    • high - more attention warranted (deadline, strategic feature, annoying bug, ...)
    • urgent - worth stopping current work (needs to be resolved quickly, bugs showing off on important systems, ...)
    • immediate - immediate action must be (possibly already have been) taken (important system is burning down, data crumbling to dust)
  • Issues, that will not be currently worked on and are being put aside for a moment, must be commented enough to enable continuation and moved to version Future or Backlog.
    • Backlog is for issues we decided to work on, new version issues are preferably chosen from here
    • Future is for nice-to-have or vaguely considered

Development cheat sheet

How to start development

Please follow the documentation for installation of prerequisites first. Now fetch the project git repository and make it work locally:

sudo apt install sudo adduser make build-essential python3 python3-venv libpython3-dev libpq-dev rrdtool librrd-dev libdb5.3 libdb5.3-dev

mkdir Workspace
cd Workspace
git clone --recurse-submodules [user]
cd mentat-ng
git checkout --track origin/release
git checkout --track origin/devel
git fetch --tags

make deps-prerequisites
. venv/bin/activate
make develop

mkdir temp
cd temp
scp .
tar -xzvf mentat_psqldb_latest.tar.gz
pg_restore --verbose --if-exists --clean --create --dbname mentat_main ./var/mentat/tmp/mentat_psqldb_daily_XXXXXX/main/

cd ..
psql mentat_events
\copy events (id, detecttime, category, description, source_ip, target_ip, source_port, target_port, source_type, target_type, protocol, node_name, node_type, cesnet_storagetime, cesnet_resolvedabuses, cesnet_eventclass, cesnet_eventseverity, cesnet_inspectionerrors, event, source_ip_aggr_ip4, target_ip_aggr_ip4, source_ip_aggr_ip6, target_ip_aggr_ip6) from ./temp/var/mentat/tmp/mentat_psqldb_daily_XXXXXX/events.dat --command init
hawat-cli db stamp head
cd migrations-events
alembic stamp head
cd ..

Usefull Git commands

# Number of commits between two commits/versions:
$ git rev-list --count v2.2.0..v2.3.0

# Total changes between two commits/versions:
$ git log --numstat --pretty="%H" v2.2.0..v2.3.0 | awk 'NF==3 {plus+=$1; minus+=$2} END {printf("+%d, -%d\n", plus, minus)}'
+16114, -13074

# Total changes in last week:
$ git log --numstat --pretty="%H" --since=1.weeks | awk 'NF==3 {plus+=$1; minus+=$2} END {printf("+%d, -%d\n", plus, minus)}'
+5827, -1622

Remove unwanted files from repository

Use case: There are files or directories in the Git repository (either by mistake, or because of some legacy policy), that should definitely not be there.
Resources: link

  1. Make sure your local repository copy is up to date, in case anything goes south
  2. Use different local copy of remote repository to make actual changes

Now execute following commands from within git repository:

# Remove DIRECTORY_NAME from all commits, then remove the refs to the old commits
# (repeat these two commands for as many directories that you want to remove)
git filter-branch --tree-filter 'rm -rf DIRECTORY_NAME' --prune-empty HEAD
git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d

# Now make sure this does not happen again
echo DIRECTORY_NAME/ >> .gitignore
git add .gitignore
git commit -m 'Removing DIRECTORY_NAME from git history'

# Clean garbage and rewrite upstream repository
git gc
git push origin master --force

Back to main page