{"id":13510686,"url":"https://github.com/pycontribs/mk","last_synced_at":"2026-03-06T19:22:20.972Z","repository":{"id":40295595,"uuid":"270276040","full_name":"pycontribs/mk","owner":"pycontribs","description":"mk ease contributing to any open source repository by exposing most common actions you can run. Inspired by make, tox and other cool tools!","archived":false,"fork":false,"pushed_at":"2025-03-31T16:52:02.000Z","size":478,"stargazers_count":105,"open_issues_count":11,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T01:57:09.968Z","etag":null,"topics":["cli","git","mk","pep-621","productivity","tox"],"latest_commit_sha":null,"homepage":"https://mk.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pycontribs.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ssbarnea"]}},"created_at":"2020-06-07T10:52:45.000Z","updated_at":"2025-03-25T15:02:16.000Z","dependencies_parsed_at":"2023-11-13T18:24:53.775Z","dependency_job_id":"eba99c2b-cf66-4aa7-a8db-662d9802a5c7","html_url":"https://github.com/pycontribs/mk","commit_stats":{"total_commits":143,"total_committers":7,"mean_commits":"20.428571428571427","dds":0.3496503496503497,"last_synced_commit":"439d5058cbcad35eae587ce28fc456688da40ad3"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycontribs%2Fmk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycontribs%2Fmk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycontribs%2Fmk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pycontribs%2Fmk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pycontribs","download_url":"https://codeload.github.com/pycontribs/mk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633467,"owners_count":21136872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","git","mk","pep-621","productivity","tox"],"created_at":"2024-08-01T02:01:49.773Z","updated_at":"2026-03-06T19:22:20.962Z","avatar_url":"https://github.com/pycontribs.png","language":"Python","funding_links":["https://github.com/sponsors/ssbarnea"],"categories":["Python","cli","Development","\u003ca name=\"programming\"\u003e\u003c/a\u003eProgramming"],"sub_categories":["Chat"],"readme":"# Documentation of mk tool\n\n`mk` is a CLI tool that aims to ease contribution and maintenance for projects\nby hiding repository implementation details from the casual contributor. With\nit, you can contribute without having to know all the build and testing tools\nthat the project team already uses, which often have strange requirements.\n\n![mk-command-line-screenshot](images/mk-social-preview.png)\n\nIf you ever asked yourself one of the below questions, probably you would want\nto try `mk` and if it can help you\n\n- How do I run tests locally?\n- Which are the test suites I can run?\n- Is my change ready to be reviewed?\n- How can I propose a change for review?\n\nRun `mk` inside any cloned repository to display which options you have. No\nconfiguration file is needed as the tool will look for common tools used by the\nrepository and expose their commands.\n\n`mk` is inspired by tools such [make][make], [waf][waf], [taskfile][taskfile],\n[tox][tox], [nox][nox], [npm][npm], [yarn][yarn] and [prek (pre-commit)][prek],\nbut **it does not aim to replace them**. Instead, it aims to provide a unified\ninterface for calling them that is friendly even for those that never used these\ntools.\n\n## Installation\n\nWe recommend using [`pipx`](https://pipxproject.github.io/pipx/) to install `mk`\nto avoid potential dependency conflicts. You can use `pip3 install --user mk` as\nwell.\n\n```shell\npipx install mk\n```\n\n## How it works\n\n`mk` inspects the current core repository and detects build tools used by the\nproject, like pre-commit, tox, npm and exposes their commands to the user in a\n**predictable** way.\n\nFor example, you should be able to lint any code repository running only\n`mk lint`, regardless of author preference for picking one way to execute them\nor another.\n\nBe assured that `mk` does not make use of AI to guess what needs to run. As most\nprojects use relatively similar patterns, it is easy to identify the one to\nexecute.\n\nAt this moment, if two tools expose the same command name, the tool will add a\nnumber to its name. In the future, we may decide to either chain them under a\nsingle name or allow some tools to shadow others and avoid duplicates.\n\n## What are the main benefits\n\nOne of the benefits of `mk` is that it should reduce the amount of\nhow-to-contribute documentation the author needs to write.\n\nA considerable amount of maintainer effort can go into producing documentation\nthat makes it easier for someone to contribute.\n\nSome projects are less affected than others. That is usually related to how well\nthe potential contributors know the practices used by the project. Still, if\nyour project has a wide range of uses, you will quickly discover that newbie\ncontributors may hit a knowledge wall. Such a barrier will likely prevent most\nof them from becoming active contributors. The remaining ones will flood the\nproject with questions, distracting other maintainers from doing more advanced\ntasks.\n\nUnless you want to deter contributions, you should plan to make it as easy as\npossible for people to contribute. That is one area where `mk` aims to help.\n\n## Aliases\n\nSimilar to [git aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases),\n`mk` allows typing as little as possible by automatically aliasing commands. For\nexample, you can run `mk lint` just by typing `mk l` as long there is no other\ncommand starting with the same letter. Aliases are available for one, two and\nthree letters prefixes.\n\n## Using mk to propose changes to projects\n\nInstead of writing a long list of tasks to follow, we can use a tool that tells\nhim what to do next. For example, `mk` has a built-in command named `up(load)`\nthat aims to ease preparing a local change from being proposed to the project.\n\nThis command detects if it should use GitHub workflow or Gerrit and will run the\nappropriate commands for opening or updating a CR/PR. Users will be allowed to\nupload a change only after passing the minimal set of local tests, preventing\nnoisy mistakes or clog CI/CD pipelines.\n\nIn addition to linting, it will also check that the repository is not in dirty\nstatus or that the testing did not leave untracked files.\n\n## Planned features\n\n- A persistent state of each command run - This means that it will know if a\n  specific command was run and if it failed or not. The state would be linked to\n  the repository state, so modifying a tracked file would reset the state to be\n  unknown. (#20)\n- Configuration file where additional actions can be added. (#21)\n- Dependencies between commands. While some tools support dependencies, many do\n  not. You should be able to declare that a specific command will run only after\n  another one already passed. (#22)\n- Ability to generate CI/CD pipelines so the user would spend less time writing\n  non-portable configurations. (#23)\n\n[make]: https://www.gnu.org/software/make/\n[nox]: https://nox.thea.codes/en/stable/\n[npm]: https://www.npmjs.com/\n[prek]: https://github.com/j178/prek\n[taskfile]: https://taskfile.dev/#/\n[tox]: https://github.com/tox-dev/tox/\n[waf]: https://waf.io/\n[yarn]: https://yarnpkg.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycontribs%2Fmk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpycontribs%2Fmk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpycontribs%2Fmk/lists"}