Git Project Manager

• Git Project Manager
  • Project Management Format
  • What you gain
  • What you lose
  • Principle
  • Why org-mode and not markdown?
• Why is this important?
• After that

Principle: put project management info along the repository not in some DB.

Git Project Manager

Put a project management tool in git.

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.

Project Management Format

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 /yogsototh/gpm/src/commit/ee7fe89d120d3f38a6200ad6aac0491082de9526/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

What you gain

• 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

What you lose

• 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.

Principle

The principle is quite easy:

1. create a gpm branch

2. put all necessary stuff in here:

   • issues list
   • ability to make comment/review/organize based on org-mode files
   • 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.

Why org-mode and not markdown?

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.

Why is this important?

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.

After that

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 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