Main repository URL is: https://gitlab.esy.fun/yogsototh/gpm
Principle: put project management info along the repository not in some DB.
Clone the project, get the code, but also the issues, the doc, the webpage, everything…
Put a project management tool in your git repository.
In general each project in git also need a lot of meta data informations. Most of them related to project management:
- issue tracker with underlying discussions
- meta documentation about the project (a wiki for example)
- code review discussions
The current status is to use something like github/gitlab/gitea for that. But it means all infos aren’t tracked inside your repository. So when someone clone your repo, he can’t have access to all project management history.
On the other hand, you don’t want to cripple all your commit messages with thousands of small commit related to project management.
An easy way to have best of both world is simply to create a branch dedicated to project management only.
For now you should simply clone it, install stack and build it.
> cd $HOME/my-git-repo > gpm init ... > gpm new-issue -i ... > gpm serve start ... > open http://localhost:1234 ... > cd /tmp; git clone git://localhost:9418/my-git-repo.git my-git-repo ... > cd my-git-repo > git checkout -b new-feature > ... /hack/ ... > git commit > ...
The easiest way would be to launch gpm or gpm --help to have the list of
commands.
Git Project Manager Usage: gpm (init | new-issue | review | serve | hooks) Available options: -h,--help Show this help text Available commands: init Initialize gpm new-issue Create a new Issue review Review (use current branch by default) serve Serve the git to the web hooks Handle hooks for this git repository
> gpm init --help Usage: gpm init Initialize gpm Available options: -h,--help Show this help text
> gpm new-issue --help
Usage: gpm new-issue [-i|--interactive] [-p|--priority PRIORITY]
[-s|--status STATUS] [-t|--title TITLE]
[-c|--creator CREATOR] [-b|--branch BRANCH]
[-g|--tags TAGS] [-a|--assignee ASSIGNEE]
[-r|--reviewers REVIEWERS] [-d|--descr DESCR]
Create a new Issue
Available options:
-i,--interactive Interactive mode
-p,--priority PRIORITY Priority A,B,C
-s,--status STATUS The status of the issue (TODO, QUESTION, ...)
-t,--title TITLE The status title
-c,--creator CREATOR The user that created the issue
-b,--branch BRANCH The branch related to the issue
-g,--tags TAGS comma separated tags
-a,--assignee ASSIGNEE Assignee
-r,--reviewers REVIEWERS comma separated reviewers
-d,--descr DESCR Long issue description
-h,--help Show this help text
To edit an issue, manually change your branch to gpm and edit the issues.org
file.
You can start a review, it will handle the task of creating a file where you can
annotate your comments. It will then create a file in
reviews/<branch-name>-<reviewer>.org.
The review process is quite open even if some helpers are provided.
> gpm review --help
Usage: gpm review (accept | feedback | question | request-change | reject |
start | end | show | retrieve)
Review (use current branch by default)
Available options:
-h,--help Show this help text
Available commands:
accept Accept the merge
feedback Provide a feedback
question Ask a question
request-change Request some Changes to merge
reject Reject the merge
start Start a new review
end End a review
show Show the review
retrieve Retrieve all the reviews for current branch
Expose a minimal read-only web interface of your repositories.
And serve the repository using git protocol.
- Web interface http://localhost:1234
- Git repository
git://localhost:9418/your-repo-name
> gpm serve --help Usage: gpm serve (start | stop | update | path) Serve the git to the web Available options: -h,--help Show this help text Available commands: start Start to serve all gpm tracked repositories stop Stop to serve all gpm tracked repositories update Update the served git repository path Show the path of the bare repository
Synchronize hooks in all your repositories.
> gpm hooks --help Usage: gpm hooks sync Handle hooks for this git repository Available options: -h,--help Show this help text Available commands: sync Synchronize hooks from gpm branch
One of the goal of this project is to handle a lot of things handled by github but with minimality. Everything used here is open source and really easy to use.
I tend to prefer pull request only, that is far easier not to handle identities through web authentication mechanism.
I think the best decentralized system to handle identities are GPG keys.
And we are lucky, you can sign all your commits with GPG.
And to promote that system, this repository provide a hooks to only accepts push/pull if all the commit are signed via a list of authorized GPG keys.
Managing the CI/CD through another 3rd party parallel branch is not simple. Mainly part of the CI/CD script directly depends on some code change, and as so, should be present in the dev branches. But also part of the code should be independant. So the question on how to handle ops code is still open for me.
My current idea would be to:
- Have a sub directory
ops/along the source code that should contains:- a
test.shscript: launch the tests, if it contains the argsallthen it should perform classical tests AND integration tests (it is up to your code not to perform integration tests by default). - a
build.shscript able tobuildand copy the resul in aops/dist/dir.
- a
So that would kind of make the process kind of “standard” for CI. And it will be easy to write a hook to perform a test and a build when necessary. Typically after fetching a new branch suitable for pull request.
Regarding deployement (and CD). It should only use the result of the build (in
ops/dist/). And take care of all deployment details. Certainly the code taking
of those details could have its place in a specific branch or in a directory
in the gpm branch.
As one goal is also to provide minimal friction I wouldn’t advise to use tools that are DBs, even puting that info in a JSON file doesn’t fit that constraint.
So I advise to use plain text files. Still I would advise to use a kind of known format or something easy to parse.
There are plenty of tools using TODO lists as plain text files:
- use your own markdown format
- https://taskell.app use a markdown
- http://todotxt.org use a specific easy to parse format
- https://orgmode.org use the org-mode format
- emacs
- vim vim-orgmode
- http://mooz.github.io/org-js/
I encourage everybody to use org-mode. Because even if you prefer markdown syntax, org-mode was designed to handle todolist unlike markdown which was designed as a readable text format to write webpage, doc, etc…
Using pandoc, it is easy to convert org-mode to any known format. But as emacs is more advanced you’ll lose some meta informations in the process.
I might try to explain that choice of org-mode more in detail. But know that it is easy to edit with any text editor, its just a bit different as compared to markdown.
I was surprised to discover that with org-mode and plain text file you can go a very long way toward project management organisation:
- issues, bug tracking, comments
- handling with minimal firction code reviews
- ability to integrate with any organization workflow you would like:
- basic trello
- scrum
- kanban
- professional kanban taking into account epic, user story writing, QA & Ops team
Be my guest. I provide examples on how to achive this in the templates/issues.org
The goal is to have most features that github provide but using only text files and git. Typically solve the problem that github is fully centralized.
- github centralized a lot of stuff which are metas infos out of your git project:
- have a unique URL to reference your project and be able to push your code to
- issue tracker
- forum to discuss about issues
- code review
- ability to make pull requests
- github pages
- project/code discovery
- identification and trust
- Perfectly self-hosted
- private
- keep history of meta infos about your projects (life of issues, etc…) in your repository
- text + git, no magic, if you don’t want to use emacs with org-mode, just use notepad it will be perfectly fine.
- keep history of reviews inside your git repo
- the meta history doesn’t pollute the project history
- github login/identification
- github discoverability. It is up to you to share your work on search engines.
- you need to self host: you’ll certainly need to buy a domain name, have a server somewhere to host a git repo.
So the goal is to prevent project management commits to cripple in the real project commits. For that, we simply use another branch that should be prevented to be merged by hooks.
The principle is quite easy:
- create a
gpmbranch - put all necessary stuff in here:
- issues list
- ability to make comment/review/organize based on
org-modefiles - code review via
org-annotate-file - hooks to share with all contributors
- webserver to provide a webpage for your project
- webserver to serve you git project to the world with potential open Pull requests.
Great advantage of org-mode is that its simple flat text files.
Anybody can edit it. Even the use of org-annotate-file is just something
anyone can do manually quite easily, create a file with all your comments
with links to the file (can also precise the line).
Of course using emacs or vim-orgmode plugin might really help.
We don’t use markdown because we can handle more complex workflow with orgmode. markdown wasn’t created to deal with todo list, etc… Org-mode file can handle meta-datas, can be presented with columns, sorted, can provide agenda views, etc…
Org mode is a format that is extremely flexible and battle tested. It is text only, readable, easy to parse.
It will adapt easily between the beginning and the end of your project life. Starting with only basic features (TODO / INPROGRESS / DONE)
Then, priority, multiple users, tags, many meta infos by task. Task organized as tree of tasks and subtasks.
It is very important to put all those meta-data about your project inside the repository because:
- you are no more dependant on any 3rd party tool to manage your project
- you can easily change how you host your git project
- anyone with just a text editor can manage those tasks.
A goal is to complete the gpm tool with a few other one all isolated but which
could all work together.
- hook handling (so all your team member can share nice hooks, for example, preformat commit messages, launch tests before publishing a pull request, etc…)
- minimal web interface to navigate your project management related files, commits, branches, etc…
- identity handling so hand in hand with hook handle and web interface provide the ability to manage how contributor can access your tool
With this system it will be more about a pull from other than wait for them to push. The identity system should be decentralized and based on GPG keys.
Mainly each user should sign their commit with their GPG key. Each user could then keep serving their local repo (see instaweb).
And more importantly, there will be “known” repositories, known packages and libraries. It will be enough to sign all those activities and to publish them on some page automatically. Or to search for the fingerprint of the GPG on the web via a search engine. You’ll then see all the activities related to that key.
Typically:
- OSS contributions
- web blog articles
- micro blog messages
- comments
- etc…
One great advantage of that, is that each user will be able to manage different GPG key pairs for dealing with different aspect of their lives.
This solution won’t need common consensus network à la bitcoin, or any decentralized smart contract system. And from my point of view, this is a lot better. Because most of those decentralized system want you to adopt their centralized system, their software, their ecosystem. While just providing a website with a list of links where the user could simply grab them and check all link correspond to a signed activies is clearly totally open source compliant and does not require any software choice on any parties. This is yet again, just a text file somewhere and a simple web service. With minimal tooling that could be coded in any language in not much time.