ACF Guidelines for Intemediary Reports and Project Management

aeternity is a public good which was made possible due to the support from a world wide community that believes in the impact of Blockchain technology.

The purpose of the aeternity crypto foundation is to support the Open-source research and development of the aeternity ecosystem in a sustainable manner. Therefore, technical maintenance, research and development grants are provided on an ongoing basis. Anyone in the world can apply.

Even though the work of grant recipients will be Open-source and available to anybody at all times in an Open Access manner, it is still important to actively update the community via intemediary reports on the progress, goals and challenges during the research.

This is why the aeternity crypto foundations is issuing guidelines for active community participation and reporting towards the entire community by grantees.

The goals of each grantee's work on the aeternity ecosystem should be:

• Open
• Transparent
• Collaborative
• Educative
• Active Outreach

Guideline: Intemediary Reports

Research documentation

Every potential and active work item must be tracked in the product's project management system and described in sufficient detail to allow community members and other contributors to follow the progress and potentially engage in further discussions.

Intemediary Reporting

To facilitate community involvement each grantee is expected to publish frequent reports on the community forum which satisfy the following requirements to a reasonable degree. Details might vary due to the nature of the grant (technical, non-technical).

• Must be written in English
  • Translations of a report are nice to have
• Must start with a short introduction to the project to inform new readers
  • Should include references existing (older) project information
• Must list current high-priority work items and their status
• Must list completed work items including the following information
  • Title
  • Description
  • Links to
    • Discussion / technical design
    • Result / Implementation
• Should mention other contributors who contributed to the aforementioned work items
• Can mention take aways for the grantee or the product
• Can list community discussions (e.g. in the forum) and other public related
  material (e.g. blog posts)

Grantee's are expected to adjust their reporting based on community feedback in terms of frequency, detail and coverage.

Every week there is an open public R&D community update call which is recorded and
shared via YouTube. Participation for one grantee per team is mandatory.

Additional Requirements for Technical Grants

To unify reporting, design and documentation as well as technical implementation all tasks, bugs, requests and issues must be publicly tracked through product's project management system (mostly GitHub Issues) and source control system (mostly Git on Github).

Documentation with example usage and demos

If applicable, all functionality needs to be documented and include example usage. All documentation must be on GitHub and should be organised in a tool like read-the-docs or mkdocs. Example usage should be treated like tests (that can break) and that should be automatically run with every new version.

Guideline: Project Management on Github

The proposal outlines the use of Github as the singular tool to handle technical projects related to aeternity.

Goals

• Transparency
  Community members and developers shall easily find all resources and be able to follow processes.
• Low Barrier of Entry
  Enable community members to get involved
• Coordination
  Allow projects to share milestones and processes

Status Quo

Most technical projects require 3 tools:

• Source code managements system (e.g. Git)
• Project management system (e.g. Pivotal Tracker)
• Support system (e.g. Issues on Github)

The technical Open-source research projects under the umbrella of ACF grants use various combinations of tools for these tasks. The different tool per Open-source research project allows each team to use their preferred tool, but makes it hard to move between Open-source research projects let alone contribute to multiple Open-source research projects. This is true even for active aeternity developers.

Example Setups

• Core protocol: Git on Github, PM on Pivotal Tracker, Support on Github
• Python SDK: Git on Github, PM (light) on Github, Support on Github
• Payments aepp: Git on private Gitlab, PM on private Gitlab, Support on Rocket Chat

Using Github

In regards to project management Github is more a framework than a fixed set of processes. It provides the basic building blocks to implement project management processes using Issues, Labels, Milestones and Bots. As such using Github for project managements requires effort, both initially and ongoing. Therefore, it is best to share the PM processes between projects to be able to re-use Bots and labeling logic.

Any size of Open-source research project should use Issues, Milestones, Labels and PRs. Large Open-source research projects should also use Github Projects.

Advantages

• Single source of information
• Project management close to the code
• Support close to the code

Disadvantages

• Time and effort required to migrate
• Complex rules can be hard to implement
• Large Open-source research projects can become hard to navigate, require use of Github Projects

Using Issues

Issues serve as the means for users to provide feedback in the form of bug reports or feature requests. Moreover, team members should use issues to capture work items.

As a general rule of thumb no work should be done without an appropriate issue being present. This ensure that all work has a minimum amount of documentation and can be attributed later on. Also the result is that any PR must link to at least one issue.

Using Labels

Labels are the glue between issues and PRs as they can be applied to both. While being very generic, labels can be purposefully named to allow proper categorization of issues and PRs.

At a minimum the following categories should be used:

• area for differentiating between parts of the project, e.g.
  • area/core
  • area/api
  • area/tests
• kind for differentiating between types of changes/requests, e.g.
  • kind/feature
  • kind/bug
  • kind/cleanup
• priority for differentiating priorities of changes/requests, e.g.
  • priority/low
  • priority/medium
  • priority/high
• needs for showing required actions to changes/requests, e.g.
  • needs/kind
  • needs/rebase
  • needs/triage
  • needs/priority
  • needs/area