{ "info": { "author": "Transifex Devs", "author_email": "info@transifex.com", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3.6" ], "description": "Totem\n-----\n\nTotem is a Health Check library that checks whether or not certain quality standards are followed on Pull Requests or local Git repositories.\n\nIt is inspired by the [Transifex Engineering Manifesto (TEM)](https://tem.transifex.com/), a document that defines the Quality Standards used in [Transifex](https://www.transifex.com). Totem was created as an automated way to ensure high quality in Git-related guidelines described in the TEM. \n\nCurrently it supports Github Pull Requests only, but can also be used locally.\n\n\n# Features\n- Multiple quality checks on Pull Requests\n- Multiple quality checks on local Git repositories \n- Comes with [pre-commit](http://www.pre-commit.com) support, and can also be added as a pre-push Git hook\n- Configurable: you can only enable the checks you want, and define the configuration parameters for each check\n- Detailed report in the console, makes it easy to spot issues\n- Compact summary shown as a comment created on the Pull Request, with configurable content (disabled by default) \n\n\n# Checks\n\nTotem supports the following checks:\n\n- **branch_name**: the name of the branch must follow a certain regex pattern\n- **pr_title**: the title of the Pull Request must follow a certain regex pattern\n- **pr_body_checklist**: the body of the Pull Request must not contain any unfinished checklist item\n- **pr_body_excludes**: the body of the Pull Request must not contain certain strings\n- **pr_body_includes**: the body of the Pull Request must contain certain strings\n- **commit_message**: the message of each commit must follow these guidelines:\n * subject:\n * has a minimum and maximum allowed length\n * must follow a certain regex pattern, e.g. start with an uppercase character and *not* end with a '.'\n * body\n * if there is a body, each line has a maximum allowed length\n * if the number of total changed lines in a commit is above a certain threshold, a body must be present and must have a minimum number of lines\n\nWith a custom configuration, you can define which checks will be executed. All of the checks have at least a certain level of configuration. \n\n## Failure level\nIf a check is executed but fails to pass, it can either provide a failed status check (exit status = 1) or simply print out a warning.\nThe former can be used in order to prevent a Pull Request from being merged, a local commit to be completed, or local changes to be pushed to the remote, until all Totem checks are fixed.\nThe latter is mainly used as a sign that something might not be right, and can be useful when comitting in or pushing from a local repo, or when reviewing a Pull Request. The warning level is necessary because in some repos a rule may not be always applicable, so it should be judged on a case-by-case basis. \n\n\n# Installation\nTotem can be installed by running `pip install totem`. It requires Python 3.6.0+.\n\n# Running on a PR\n## Command line\nTotem provides a console command and requires only the URL of the pull request to check. \nBy default, it will attempt to read the `.totem.yml` file on the repo as configuration. If it is not found, it defaults to `./contrib/config/sample.yml` on the Totem repo.\n\n```\ntotem -p https://www.github.com/:owner/:repo/pulls/:number\n```\n\nExample:\n```\ntotem -p https://github.com/transifex/totem/pull/17\n```\n\nNOTE: the default configuration will *not* create a comment on the Pull Request being checked. If you use a custom config, you can enable the comment feature. \n\nA custom config can be provided and supports a lot of options.\n\n```\ntotem -p https://www.github.com/:owner/:repo/pulls/:number -c ./totem_config.yml\n```\n\nThe project includes a sample configuration file, which can be found at `./contrib/config/sample.yml`.\n\n## CI\nWhen running from a CI service, you need to retrieve the pull request URL from the environment variables the service provides. Also, you can set the URL of the CI build page, in which case a link appears on the PR comment that the Totem creates.\n\nFor example, you make a call like this:\n```\ntotem --pr-url \"\" --config-file \".totem.yml\" --details-url \"\"\n```\nwhere `` is a variable given from the CI service. For example, for CircleCI it's `$CIRCLE_PULL_REQUEST`.\n\n### Github authentication\nIn order to run Totem on pull requests of private projects, as well as in order to be able to enable reporting in PR comments, the tool needs to be authenticated when contacting Github. In order to do that, you need to add an environment variable with the Github access token to your CI service:\n`GITHUB_ACCESS_TOKEN=`\n\nYou also need to authorize add a deploy key on the CI service. For example, on Circle CI go to the project Settings > Permissions > Checkout SSH keys and click on [Add Deploy key].\n\nAn example of a complete setup on a CI, together with GitHub authentication, looks like this:\n```yaml\njobs:\n totem:\n docker:\n - image: python:alpine\n environment:\n steps:\n - checkout\n - add_ssh_keys:\n fingerprint:\n # a public deploy key of the current repository on GitHub, something like:\n \"8a:32:b1:d4:24:12:c4:33:8f:ac:0f:37:c8:84:c4:cc\"\n - run:\n name: Install git/openssh-client and add github to the list of known hosts\n command: apk add git openssh-client && mkdir ~/.ssh && ssh-keyscan github.com > ~/.ssh/known_hosts\n - run:\n name: Install totem\n command: pip install totem\n - run:\n name: Run Totem\n command: totem --pr-url \"\" --config-file \".totem.yml\" --details-url \"\"\n``` \n\n### CircleCI\nKeep in mind that because of a bug in CircleCI, sometimes the `$CIRCLE_PULL_REQUEST` variable is empty. If the pull request argument in the `totem` CLI command is empty, Totem runs in local mode because there is no pull request to check. This can create false positives (that everything is OK when in fact it's not). Therefore, in order to run Totem without the false positives, the following workaround can be used: \n```shell\nif [[ \"$CIRCLE_BRANCH\" == \"devel\" || \"$CIRCLE_BRANCH\" == \"master\" ]]; then\n echo \"Totem is disabled on branch '$CIRCLE_BRANCH'. Won't execute.\"\nelse\n if [[ \"$CIRCLE_PULL_REQUEST\" == \"\" ]]; then\n echo \"\\$CIRCLE_PULL_REQUEST is empty. It's probably due to CircleCI's bug\"\n echo \"(https://discuss.circleci.com/t/circle-pull-request-not-being-set/14409).\"\n echo \"Please rerun the workflow until the PR variable is populated by CircleCI.\"\n exit 1\n else\n totem --pr-url \"$CIRCLE_PULL_REQUEST\" --config-file \".totem.yml\" --details-url \"$CIRCLE_BUILD_URL\"\n fi\nfi\n```\n\nThe script above does not run Totem if the current branch is `devel` or `master`, which means that it's running on a merge commit. Of course, these are just sample branches and may differ from the base branches you have in your workflow. \n\n\n# Running on a local repository\n\nYou can call the command without any arguments. In this case it reads the `.totem.yml` file on the repo as configuration. If this file does not exist, the tool cannot run.\n```\ntotem\n```\n\nYou can also define a custom config file to use.\n```\ntotem -c \n```\n\nThe local mode of Totem runs only a subset of the available (and enabled) checks:\n- **branch_name**: the name of the branch must follow a certain regex pattern\n- **commit_message**: the message of each commit must follow certain guidelines\n\nThe reason is that the rest of the checks require a Pull Request, which is not available locally. \n\n\n## Pre-commit hook\nIn order to use it as a [pre-commit](http://www.pre-commit.com) hook, add the following in your `.pre-commit-config.yaml` file.\n\n```yaml\n- repo: https://github.com/transifex/totem/\n rev: master\n hooks:\n - id: totem\n```\n\nMake sure you follow the instructions given in [pre-commit](http://www.pre-commit.com) on how to install and use the hooks.\nAs soon as you do that, Totem will run every time you attempt to create a new commit and will abort the command in case any checks fail. Note that it will not abort in case of warnings. \n\n\n## Pre-push hook\n\nIn order to use it as a pre-push hook, add the following in the `.git/hooks/pre-push` file:\n```\n#!/bin/sh\ntotem\n```\n\nNote: Make sure the file is executable (`chmod +x .git/hooks/pre-push`).\n\nThis way, totem will run every time you call `git push`, and will abort the command in case any checks fail. Note that it will not abort in case of warnings.\n\n\n# Configuration\nThis is a sample configuration that contains all available options:\n\n```yaml\nsettings:\n pr_comment_report:\n enabled: True\n show_empty_sections: True\n show_message: True\n show_details: True\n console_report:\n show_empty_sections: True\n show_message: True\n show_details: True\n show_successful: True\n local_console_report:\n show_empty_sections: False\n show_message: True\n show_details: True\n show_successful: False\nchecks:\n branch_name:\n pattern: ^[\\w\\d\\-]+$\n pattern_descr: Branch name must only include lowercase characters, digits and dashes\n failure_level: warning\n pr_title:\n pattern: ^[A-Z].+$\n pattern_descr: PR title must start with a capital letter\n failure_level: warning\n pr_body_checklist:\n failure_level: error\n pr_body_excludes:\n patterns:\n - excl1\n - excl2\n failure_level: error\n pr_body_includes:\n patterns:\n - incl1\n - incl2\n failure_level: error\n commit_message:\n subject:\n min_length: 10\n max_length: 50\n pattern: ^[A-Z].+(?