Git-IssueManager/lib/Git/IssueManager.pm

768 lines
16 KiB
Perl
Raw Normal View History

2018-07-04 10:46:13 +02:00
package Git::IssueManager;
#ABSTRACT: Module for managing issues in a git branch within your repository
use Moose;
2018-07-04 18:33:10 +02:00
use MooseX::Privacy;
2018-07-04 10:46:13 +02:00
use DateTime;
use DateTime::TimeZone;
use Data::Dumper;
2018-09-10 22:41:49 +02:00
use Git::LowLevel;
use Git::IssueManager::Issue;
2018-07-04 10:46:13 +02:00
2018-09-13 22:06:59 +02:00
=head1 DESCRIPTION
Git::IssueManager is a Perl Module for using git as an issue store creating a
B<distributed issue management system>.
It uses the Git::LowLevel Module to store issues in a B<issue> branch using trees
and blobs.
=head2 EXAMPLE
use Git::IssueManager;
my $manager = Git::IssueManager->new(repository=>Git::LowLevel->new(git_dir=> "."));
if (!$manager->ready)
{
print("IssueManager not initialized yet. Please call \"init\" command to do so.");
exit(-1);
}
my @issues=$manager->list();
for my $i (@issues)
{
print $i->subject . "\n";
}
=head2 MOTIVATION
Issue management is an essential part in modern software engineering. In most cases tools
like I<jira> or I<github> are used for this task. The central nature of these tools is a large
disadvantage if you are often on the road. Furthermore if you are using I<git> for version
control you have everything available for B<distributed issue management>.
B<Advantages:>
=over 12
=item save your issues within your project
=item manage issues on the road, without internet access
=item write your own scripts for issue management
=back
B<Disadvantages:>
=over 12
=item no easy way to let users add issues without pull request yet
=item not all functions implemented yet
=back
=head2 FEATURES
=over 12
=item add issues
=item list issues
=item assign workers to an issue
=item start and close issues
=item delete issues
=back
=cut
2018-09-10 22:41:49 +02:00
=attr gitcmd
the path to the git command, default is using your path
=cut
has 'gitcmd' => (is => 'ro', isa => 'Str', default=>"git");
2018-07-04 10:46:13 +02:00
=attr repository
Git::Repository object on which to do the issue management
=cut
2018-09-10 22:41:49 +02:00
has 'repository' => (is =>'rw', isa => 'Git::LowLevel');
2018-07-04 10:46:13 +02:00
2018-07-04 18:33:10 +02:00
=attr _open
B<private attribute>
=cut
2018-09-10 22:41:49 +02:00
has '_open' => (is => 'rw', isa => 'Git::LowLevel::Tree', traits => [qw/Private/]);
2018-07-04 18:33:10 +02:00
=attr _assigned
B<private attribute>
=cut
2018-09-10 22:41:49 +02:00
has '_assigned' => (is => 'rw', isa => 'Git::LowLevel::Tree', traits => [qw/Private/]);
2018-07-04 18:33:10 +02:00
=attr _inprogress
B<private attribute>
=cut
2018-09-10 22:41:49 +02:00
has '_inprogress' => (is => 'rw', isa => 'Git::LowLevel::Tree', traits => [qw/Private/]);
2018-07-04 18:33:10 +02:00
=attr _closed
B<private attribute>
=cut
2018-09-10 22:41:49 +02:00
has '_closed' => (is => 'rw', isa => 'Git::LowLevel::Tree', traits => [qw/Private/]);
2018-07-04 18:33:10 +02:00
=attr _root
B<private attribute>
=cut
2018-09-10 22:41:49 +02:00
has '_root' => (is => 'rw', isa => 'Git::LowLevel::Tree', traits => [qw/Private/]);
2018-07-04 10:46:13 +02:00
=method ready
validates if everything is in place for issue management
=cut
sub ready
{
my $self = shift;
2018-09-10 22:41:49 +02:00
my $ref = $self->repository->getReference('refs/heads/issues');
return 0 unless $ref->exist;
my $version = $ref->find('.version');
return 0 unless defined($version) && ref($version) eq "Git::LowLevel::Blob";
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
my $tag = $ref->find('.tag');
return 0 unless defined($tag) && ref($tag) eq "Git::LowLevel::Blob";
2018-07-04 10:46:13 +02:00
return 1;
}
=method version
returns the version number of the issue system within the issue branch
=cut
sub version
{
my $self = shift;
return unless $self->ready();
2018-09-10 22:41:49 +02:00
my $ref = $self->repository->getReference('refs/heads/issues');
my $version = $ref->find(".version");
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
return $version->content;
2018-07-04 10:46:13 +02:00
}
=method tag
returns the issue tag to prepend in front of all issue ids
=cut
sub tag
{
my $self = shift;
return unless $self->ready();
2018-09-10 22:41:49 +02:00
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag");
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
return $tag->content;
2018-07-04 10:46:13 +02:00
}
=method available_types
returns an array of available/supported issue types
=cut
sub available_types
{
my $self = shift;
return ("bug","security-bug","improvement","feature","task","epic");
}
2018-07-04 10:46:13 +02:00
=method init
initialize the repository for managing issues
=cut
sub init
{
my $self = shift;
my $issue_tag = shift;
return unless ! $self->ready();
2018-09-10 22:41:49 +02:00
die("no issue tag given") unless defined($issue_tag) && length($issue_tag) > 0;
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
my $ref = $self->repository->getReference('refs/heads/issues');
my $root = $ref->getTree();
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
my $version = $root->newBlob();
$version->path(".version");
$version->_content("0.1");
$root->add($version);
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
my $tag = $root->newBlob();
$tag->path(".tag");
$tag->_content($issue_tag);
$root->add($tag);
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
$ref->commit("initialized issue manager");
2018-07-04 10:46:13 +02:00
}
2018-07-04 18:33:10 +02:00
=method add
2018-09-10 22:41:49 +02:00
add an issue to the repository
first paramter is an GitIssueManager::Issue object
2018-07-04 18:33:10 +02:00
=cut
sub add
{
2018-09-10 22:41:49 +02:00
my $self = shift;
my $issue = shift;
2018-07-04 18:33:10 +02:00
die("IssueManager not initialized") unless $self->ready();
2018-09-10 22:41:49 +02:00
die("no issue given") unless defined($issue) && ref($issue) eq "Git::IssueManager::Issue";
2018-07-04 18:33:10 +02:00
2018-09-10 22:41:49 +02:00
my $ref = $self->repository->getReference('refs/heads/issues');
my $root = $ref->getTree();
2018-07-04 18:33:10 +02:00
2018-09-10 22:41:49 +02:00
my $issueTree=$issue->createIssue($self->repository);
2018-07-04 18:33:10 +02:00
2018-09-10 22:41:49 +02:00
my $base=$root->find($issue->status);
if (!defined($base))
2018-07-04 18:33:10 +02:00
{
2018-09-10 22:41:49 +02:00
$base = $root->newTree();
$base->path($issue->status);
$root->add($base);
2018-07-04 18:33:10 +02:00
}
2018-09-10 22:41:49 +02:00
$base->add($issueTree);
$ref->commit("added issue " . $issue->subject);
2018-07-04 10:46:13 +02:00
}
2018-09-10 22:41:49 +02:00
=method parseIssue
2018-07-09 21:17:13 +02:00
2018-09-10 22:41:49 +02:00
parsed the given Git::LowLevel::Tree object as an Issue
2018-07-04 10:46:13 +02:00
=cut
2018-09-10 22:41:49 +02:00
sub parseIssue
2018-07-04 10:46:13 +02:00
{
my $self = shift;
my $d = shift;
my $tag = shift;
my $status = shift;
2018-09-13 21:28:17 +02:00
my $subject = $d->find("subject");
2018-09-10 22:41:49 +02:00
my $description = $d->find("description");
my $priority = $d->find("priority");
my $severity = $d->find("severity");
my $type = $d->find("type");
my $worker = $d->find("worker");
my $substatus = $d->find("substatus");
my $comment = $d->find("comment");
my $estimated = $d->find("estimated");
my $working = $d->find("working");
my $tags = $d->find("tags");
2018-09-15 22:46:47 +02:00
my $close_commit = $d->find("close_commit");
2018-09-13 21:28:17 +02:00
my $id = $tag . "-" . substr($subject->hash(),0,8);
2018-09-15 22:24:05 +02:00
my $cd = $d->find("creation_date");
my $ld = $d->find("last_change_date");
my $cld = $d->find("closed_date");
2018-09-10 22:41:49 +02:00
my $author = $d->committer();
# check for required attributes
die("description not available for issue " . $id) unless defined($description);
die("priority not available for issue " . $id) unless defined($priority);
die("severity not available for issue " . $id) unless defined($severity);
die("type not available for issue " . $id) unless defined($type);
2018-07-04 10:46:13 +02:00
2018-09-15 22:24:05 +02:00
#required for backwards compatibility
if (!defined($cd))
{
$cd = $d->timestamp_added();
}
else
{
$cd = $cd->content();
}
#required for backwards compatibility
if (!defined($ld))
{
$ld = $d->timestamp_last();
}
else
{
$ld = $ld->content();
}
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
my $tz=DateTime::TimeZone->new( name => 'local' );
2018-09-13 21:28:17 +02:00
my $issue = Git::IssueManager::Issue->new(subject => $subject->content);
$issue->status($status);
2018-09-10 22:41:49 +02:00
$issue->description($description->content());
$issue->priority($priority->content());
$issue->severity($severity->content());
$issue->type($type->content());
$issue->id($id);
$issue->creation_date(DateTime->from_epoch( epoch =>$cd, time_zone=>$tz));
$issue->last_change_date(DateTime->from_epoch( epoch =>$ld, time_zone=>$tz));
2018-07-04 10:46:13 +02:00
2018-09-15 22:24:05 +02:00
if (defined($cld))
{
$issue->closed_date(DateTime->from_epoch( epoch =>$cld->content, time_zone=>$tz));
}
2018-09-15 22:46:47 +02:00
if (defined($close_commit) && $issue->status eq "closed")
{
$issue->close_commit($close_commit->content());
}
2018-07-04 10:46:13 +02:00
if (defined($worker))
{
2018-09-10 22:41:49 +02:00
$worker->content()=~/^(.*)\<(.*)\>$/;
$issue->worker($1);
$issue->worker_email($2);
2018-07-04 10:46:13 +02:00
}
2018-09-10 22:41:49 +02:00
if (defined($author))
2018-07-04 10:46:13 +02:00
{
2018-09-10 22:41:49 +02:00
$author=~/^(.*)\<(.*)\>$/;
$issue->author($1);
$issue->author_email($2);
2018-07-04 10:46:13 +02:00
}
2018-09-15 22:36:46 +02:00
if (defined($tags))
{
my @tag_array=split /\n/,$tags;
$issue->tags(\@tag_array);
}
2018-07-04 10:46:13 +02:00
return $issue;
}
2018-09-10 22:41:49 +02:00
sub list
2018-07-04 10:46:13 +02:00
{
my $self = shift;
2018-09-10 22:41:49 +02:00
my @issues;
2018-07-04 10:46:13 +02:00
2018-09-10 22:41:49 +02:00
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $root = $ref->getTree();
my $open = $ref->find("open");
my $closed = $ref->find("closed");
my $assigned = $ref->find("assigned");
my $inprogress = $ref->find("inprogess");
my $tag = $ref->find(".tag")->content();
my @all;
2018-07-04 10:46:13 +02:00
my @statusse = ("open","closed","assigned","inprogress");
for my $s (@statusse)
2018-07-04 10:46:13 +02:00
{
for my $status ($root->find($s))
{
for my $i ($status->get())
{
my $issue = $self->parseIssue($i,$tag,$s);
push(@issues,$issue);
}
}
2018-07-04 10:46:13 +02:00
}
2018-09-10 22:41:49 +02:00
return @issues;
2018-07-04 10:46:13 +02:00
}
=method delete
2018-07-04 16:17:12 +02:00
delete an issue from the issue list
=cut
2018-07-04 16:17:12 +02:00
sub delete
{
2018-09-10 22:41:49 +02:00
my $self = shift;
my $id = shift;
my @statusse = ("open","closed","assigned","inprogress");
2018-07-09 21:17:13 +02:00
2018-09-10 22:41:49 +02:00
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag")->content();
my $root = $ref->getTree();
for my $s (@statusse)
{
for my $status ($root->find($s))
{
for my $i ($status->get())
{
if (ref($i) eq "Git::LowLevel::Tree")
{
2018-09-13 21:28:17 +02:00
my $subject = $i->find("subject");
my $mytag = $tag . "-" . substr($subject->hash(),0,8);
if ($id eq $mytag)
{
$status->del($i);
$ref->commit("removed issue " . $i->mypath);
return;
}
}
}
}
}
die("issue " . $id . " not found\n");
2018-07-09 21:17:13 +02:00
}
2018-09-11 20:41:12 +02:00
2018-09-13 21:28:17 +02:00
=method changeStatus
2018-09-11 20:41:12 +02:00
2018-09-13 21:28:17 +02:00
set status of an issue
2018-09-11 20:41:12 +02:00
=cut
2018-09-13 21:28:17 +02:00
sub changeStatus
2018-09-11 20:41:12 +02:00
{
my $self = shift;
my $id = shift;
2018-09-13 21:28:17 +02:00
my $status= shift;
die("unknown status") unless $status eq "open" || $status eq "closed" || $status eq "inprogress" || $status eq "assigned";
my @statusse = ("open","assigned","inprogress","closed");
2018-09-11 20:41:12 +02:00
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag")->content();
my $root = $ref->getTree();
for my $s (@statusse)
{
2018-09-13 21:28:17 +02:00
next unless $s ne $status;
for my $stat ($root->find($s))
2018-09-11 20:41:12 +02:00
{
2018-09-13 21:28:17 +02:00
for my $i ($stat->get())
2018-09-11 20:41:12 +02:00
{
if (ref($i) eq "Git::LowLevel::Tree")
{
2018-09-13 21:28:17 +02:00
my $subject = $i->find("subject");
my $mytag = $tag . "-" . substr($subject->hash(),0,8);
2018-09-11 20:41:12 +02:00
if ($id eq $mytag)
{
2018-09-13 21:28:17 +02:00
my $base=$root->find($status);
$stat->del($i);
my $issue = $self->parseIssue($i, $tag, $s);
$issue->status($status);
my $issueTree=$issue->createIssue($self->repository);
if (!defined($base))
{
$base = $root->newTree();
$base->path($status);
$root->add($base);
}
$base->add($issueTree);
$ref->commit("closed issue " . $i->mypath);
return;
}
}
}
}
}
die("issue " . $id . " not found\n");
}
=method assign
assign a worker to an issue
=cut
sub assign
{
my $self = shift;
my $id = shift;
my $worker_name = shift;
my $worker_email = shift;
my $status = "assigned";
my @statusse = ("open","assigned","inprogress","closed");
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag")->content();
my $root = $ref->getTree();
for my $s (@statusse)
{
next unless $s ne $status;
for my $stat ($root->find($s))
{
for my $i ($stat->get())
{
if (ref($i) eq "Git::LowLevel::Tree")
{
my $subject = $i->find("subject");
my $mytag = $tag . "-" . substr($subject->hash(),0,8);
if ($id eq $mytag)
{
my $base=$root->find($status);
$stat->del($i);
my $issue = $self->parseIssue($i, $tag, $s);
$issue->status($status);
$issue->worker($worker_name);
$issue->worker_email($worker_email);
2018-09-11 20:41:12 +02:00
my $issueTree=$issue->createIssue($self->repository);
2018-09-13 21:28:17 +02:00
if (!defined($base))
2018-09-11 20:41:12 +02:00
{
2018-09-13 21:28:17 +02:00
$base = $root->newTree();
$base->path($status);
$root->add($base);
2018-09-11 20:41:12 +02:00
}
2018-09-13 21:28:17 +02:00
$base->add($issueTree);
2018-09-11 20:41:12 +02:00
$ref->commit("closed issue " . $i->mypath);
return;
}
}
}
}
}
die("issue " . $id . " not found\n");
2018-09-13 21:28:17 +02:00
}
=method close
close an issue
=cut
sub close
{
my $self = shift;
my $id = shift;
my $commit = shift || "";
my $status = "closed";
my @statusse = ("open","assigned","inprogress","closed");
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag")->content();
my $root = $ref->getTree();
for my $s (@statusse)
{
next unless $s ne $status;
for my $stat ($root->find($s))
{
for my $i ($stat->get())
{
if (ref($i) eq "Git::LowLevel::Tree")
{
my $subject = $i->find("subject");
my $mytag = $tag . "-" . substr($subject->hash(),0,8);
if ($id eq $mytag)
{
my $base=$root->find($status);
$stat->del($i);
my $issue = $self->parseIssue($i, $tag, $s);
$issue->status($status);
$issue->close_commit($commit);
2018-09-13 21:28:17 +02:00
my $issueTree=$issue->createIssue($self->repository);
if (!defined($base))
{
$base = $root->newTree();
$base->path($status);
$root->add($base);
}
$base->add($issueTree);
$ref->commit("closed issue " . $i->mypath);
return;
}
}
}
}
}
die("issue " . $id . " not found\n");
2018-09-13 21:28:17 +02:00
}
=method open
open an issue
=cut
sub open
{
my $self = shift;
my $id = shift;
$self->changeStatus($id, "open");
}
=method start
start an issue
=cut
sub start
{
my $self = shift;
my $id = shift;
$self->changeStatus($id, "inprogress");
2018-09-11 20:41:12 +02:00
}
=method stats
calculate some basic statistics from the current issue repository
at the moment:
number of open issues
number of assigned issues
number of inprogress issues
number of closed issues
@param none
@return hash with
{open}
{assigned}
{inprogress}
{closed}
{all}
=cut
sub stats
{
my $self = shift;
my $ref = $self->repository->getReference('refs/heads/issues');
my $open = $ref->find("open");
my $closed = $ref->find("closed");
my $assigned = $ref->find("assigned");
my $inprogress = $ref->find("inprogess");
my $ret={};
# get number of all open issues
if (defined($open))
{
$ret->{open}=int($open->get);
}
else
{
$ret->{open}=0;
}
# get number of all assigned issues
if (defined($assigned))
{
$ret->{assigned}=int($assigned->get);
}
else
{
$ret->{assigned}=0;
}
# get number of all inprogress issues
if (defined($inprogress))
{
$ret->{inprogress}=int($inprogress->get);
}
else
{
$ret->{inprogess}=0;
}
# get number of all closed issues
if (defined($closed))
{
$ret->{closed}=int($closed->get);
}
else
{
$ret->{closed}=0;
}
return $ret;
}
2018-09-15 22:04:12 +02:00
=method get
2018-09-15 22:04:12 +02:00
return an issue identified by its id
@param 1. param = id
@return Git::IssueManager::Issue object
=cut
sub get
{
my $self = shift;
my $id = shift;
my @statusse = ("open","assigned","inprogress","closed");
die("IssueManager not initialized") unless $self->ready();
my $ref = $self->repository->getReference('refs/heads/issues');
my $tag = $ref->find(".tag")->content();
my $root = $ref->getTree();
for my $s (@statusse)
{
for my $stat ($root->find($s))
{
for my $i ($stat->get())
{
if (ref($i) eq "Git::LowLevel::Tree")
{
my $subject = $i->find("subject");
my $mytag = $tag . "-" . substr($subject->hash(),0,8);
if ($id eq $mytag)
{
my $issue = $self->parseIssue($i, $tag, $s);
return $issue;
}
}
}
}
}
die("issue " . $id . " not found\n");
}
2018-07-04 10:46:13 +02:00
1;