2018-08-28 17:25:00 +00:00
|
|
|
#+Title: Git Project Manager
|
|
|
|
#+Author: Yann Esposito
|
|
|
|
|
2018-08-30 12:34:02 +00:00
|
|
|
*Principle: put project management info along the repository not in some DB.*
|
2018-08-28 17:25:00 +00:00
|
|
|
|
2018-10-09 22:19:48 +00:00
|
|
|
Clone the project, get the code, but also the issues, the doc, the webpage,
|
|
|
|
everything...
|
|
|
|
|
2018-08-30 12:34:02 +00:00
|
|
|
* 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]]
|
2018-08-28 20:52:30 +00:00
|
|
|
|
2018-08-28 17:25:00 +00:00
|
|
|
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...
|
|
|
|
|
2018-08-31 21:37:50 +00:00
|
|
|
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.
|
2018-08-30 16:33:02 +00:00
|
|
|
|
2018-08-30 12:34:02 +00:00
|
|
|
* 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
|
2018-10-06 13:55:21 +00:00
|
|
|
|
|
|
|
** 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.
|