gpm/README.org

#+Title: Git Project Manager
#+Author: Yann Esposito

*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
  [[file: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

** Identfy users, allow access and trust them

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.