Tracehub and Project as a Code, a VCS-based collaboration tool, and its robot.

Motivation. We want to keep our code, tickets, and docs in-sync. However, there is no tool to do it in flexible and configurable way. We provide both-side integration through YAML notation.

Principles. These are the design principles behind tracehub.

How to use. All you need is to register your project in pmo.

Then create project document (project.yml in the root of .trace directory, in master branch) in the following notation:

id: 5B0185CB-424B-42D4-9631-7B628B7BB78F
name: Tracehub
active: true
performers:
  - name: h1alexbel
    roles:
      - DEV
      - ARC
backlog:
  type: GitHub
  rules:
    min-words: 20
    min-estimate: 25
    max-estimate: 90
docs:
  type: Markdown
dependencies:
  - github.com/h1alexbel/cdit@master
  - github.com/tracehubpm/pmo@master

your file tree should look like this:

.trace
  project.yml
  /docs
    req.yml
    uc1.yml
    uc2.yml
  /jobs
    update-year.yml
    fix-me.yml
  /rules
    contribution.yml
  ...
...

project.yml notation

The element id is generated by tracehubpm/pmo and represents a unique UUID assigned to the project.

The element name represents the name of the project.

The element description denotes project's description.

The element active represents that project active-in-development.

Section performers for specifying who is working on the projects. Each one has the following schema:

• name: performer's name
• roles: an array of roles, that performer has

For now, we support these roles:

• PO: Product Owner
• PM: Project Manager
• ARC: Architect
• DEV: Developer, Programmer
• TEST: Tester

Section backlog represents the place where all issues from /jobs package will be placed.

• type: issue tracker type, possible values are GitHub (jobs will be registered as issues in GitHub), JIRA (jobs will be registered as tickets in Atlassian JIRA).
• rules: rules, related to the backlog, there are few: min-estimate (measured in minutes), max-estimate (measured in minutes) and min-words (amount of words in task description), all of them should be specified as positive integer values.

Section docs represents the place where all documentation from /docs package will be placed.

• type: document repository, possible values are Markdown (all docs will be formatted in markdown and placed inside root /docs directory), GitHub Wikis, Confluence.

Section dependencies denotes the repository dependencies This is can be helpful in case of multi-repository codebase management.

Inside those repositories, outlined as a dependencies (@ specifies which branch to check), you should create .trace directory inside root, in master branch as well with this configuration (project.yml):

central: github.com/tracehubpm/tracebot

Now, you inherit all the configuration from central repository.

Jobs

Jobs can be created as "work activity" for performers.

Each job must be located inside /jobs package in the .trace directory. Take a look at the example of Job document:

label: Update License year to 2024
description: |
  Lets update a copyright year in our License to 2024
cost: 20
role: ARC

The element label represents the job name. The element description represents description of the job. The element cost represents an estimation in minutes of this job, positive integer value. The element role represents a required role for assigning on the job. If not specified, then it will be DEV.

Once it committed inside master branch, @tracehubgit will create it in backlog that was specified in project.yml.

It works both sides, when somebody will create/update/delete ticket in a backlog, @tracehubgit will catch it up and create new Pull Request with your changes in your git repository.

Docs

To document something, use Documents.

Each document must be located inside /docs package in the .trace directory. Take a look at the example of it:

type: Specs
spec: |-
  ...

The element type defines the type of the document. We support these values:

• Specs, analogue of SRS
• UC, which stands for Use case
• Other, any other document you wish to have

Once it goes in master branch, @tracehubgit will create it in document repository that was specified in project.yml.

It also works both sides, when somebody will create/update/delete document in a docs, @tracehubgit will catch it up and create new Pull Request with changes in your git repository.

Rules

TBD..

Secret Variables

Avoid storing sensitive information in Git inside your YAML documents. Use this notation instead:

...
backlog:
 type: GitHub
 url: ${jira-url}
 token: ${jira-token}
 rules:
   ...
...

Both secrets jira-url and jira-token must be present in your project account inside pmo. When integration will happen, values from these secret variables will be injected instead of placeholders.

Supported platforms

We aim to support the following platforms:

Git-hosted repositories in:

• GitHub
• GitLab
• Bitbucket

Issue trackers:

• GitHub Issues
• JIRA

Document storages:

• GitHub Wikis
• Confluence

How to contribute?

It is a Java project. First install Java SDK 17+, Maven 3.8+.

Then run:

$ mvn clean install -Pjacoco

The build has to be clean. If it's not, submit an issue.

Then, make your changes, make sure the build is still clean, and submit a pull request.

If you want to run a real simulation run this:

$ mvn clean install -Psimulation -DTracehub-GitHubToken=...

Provide your GitHub token with write permissions to the next repositories:

• h1alexbel/test
• h1alexbel/invalid-project