gpm/README.org

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

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

* Git Project Manager

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.

** Installation

For now you should simply clone it, install stack and build it.

** Usage

*** Quick

#+BEGIN_SRC
> 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
> ...
#+END_SRC

*** Detailled

The easiest way would be to launch =gpm= or =gpm --help= to have the list of
commands.

#+BEGIN_SRC
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
#+END_SRC

*** Init

#+BEGIN_SRC
> gpm init --help
Usage: gpm init
  Initialize gpm

Available options:
  -h,--help                Show this help text
#+END_SRC

*** New Issue

#+BEGIN_SRC
> 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
#+END_SRC

To edit an issue, manually change your branch to =gpm= and edit the =issues.org=
file.

*** Review

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.

#+BEGIN_SRC
> 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
#+END_SRC

*** Serve

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=

#+BEGIN_SRC
> 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
#+END_SRC

*** Hooks

Synchronize hooks in all your repositories.

#+BEGIN_SRC
> 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
#+END_SRC

* Considerations

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.

** No Push?

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.

** Ops?

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.sh= script: launch the tests, if it contains the args =all= then it
    should perform classical tests AND integration tests (it is up to your code
    not to perform integration tests by default).
  - a =build.sh= script able to =build= and copy the resul in a =ops/dist/= dir.

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.

* About
** 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 friction 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 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

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