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
|
|
|
|
|
2018-10-22 07:14:54 +00:00
|
|
|
Put a project management tool in your git repository.
|
2018-08-30 12:34:02 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2018-10-22 07:14:54 +00:00
|
|
|
** 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
|
2018-10-22 08:55:39 +00:00
|
|
|
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.
|
2018-10-22 07:14:54 +00:00
|
|
|
|
|
|
|
** 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.
|
|
|
|
|
2018-10-22 08:55:39 +00:00
|
|
|
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.
|
|
|
|
|
2018-10-22 07:14:54 +00:00
|
|
|
* About
|
2018-08-30 12:34:02 +00:00
|
|
|
** 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-10-22 07:14:54 +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 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.
|