Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
79 lines (56 sloc) 7.61 KB

NIP 3 - Documenting a new feature

    NIP: 3
    Title: Documenting a new feature
    Author: David Garcia <david@nem.foundation>
    Discussions-To: #sig-docs
    Comments-URI: https://github.com/nemtech/NIP/issues/9
    Status: Draft
    Type: Process
    Created: 2019-01-23
    License: BSD-2-Clause

Table of contents

Introduction

This NIP introduces a detailed process to document a new feature.

Motivation:

  1. Define collaboration between different SIG regarding docs.
  2. Include documentation in the definition of done.
  3. Enable docs collaboration in the different stages.
  4. Increase the availability of new information related to development.

Glossary:

  • NIP: NEM Improvement Proposal
  • SIG: Special Interest Group
  • PMC: Project Management Committee

Process

diagram

Features: Features are treated as single entities, independently of the milestone they belong. This allows merging changes without waiting for other features pending to be finished.

Phases: As we are collaborating between different parties in a remote setup, it is necessary to share materials once ready in different moments. As a general rule, don’t pre-announce in master a feature that has not been released in at least the catapult-server repository.

Phase Deliverables Action
Specification Accepted NIP (NIP author) Create a new branch in nem2-docs repository using the NIP’s identifier.
Feature is available in catapult-server Server Deliverables (SIG-Server) and Concept (SIG-docs) a) Publish concept(*).
b) Merge to master.
Translations can start.
Feature becomes testable Endpoints (SIG-api) and Swagger (SIG-docs) a) Publish updated swagger file.
b) Publish the list of required guides as open Github issues in nem2-docs repository.
Feature becomes usable SDK comments (SIG-api), SDK reference (SIG-docs) and Guides (SIG-docs + community) a) Publish SDK docs.
b)Publish guides.

(*) If the feature is not testable or usable, e.g. SDK is not usable but REST is advanced, this should be remarked in the documentation. Once the feature reaches the master branch, it can be promoted by the different stakeholders as a newly included feature.

Participants: Each group should provide the required documentation in the specified format (see Annex: Deliverables). Keeping the nem-docs repository updated and supervise the documentation process is the responsibility of the SIG-doc.

Revision: At least two different people form the SIG-docs should review the changes before the committer merges them to master.

Annex: Deliverables

Deliverable Description Template
Accepted NIP Document describing specification and the design decisions for a new NEM feature. Note: Accepted NIPS require to be publicly available after RC release. NIP Structure The specification may have as annex some behavior scenarios to drive the development.
Concept The specification formatted for documentation. Feature explanation, Examples and schemas.
Server Deliverables The required pieces of documentation around the server changes. Changelog (published in the catapult-server repository), Status Errors (Result.h validators), Entity Schemas and configuration changes.
Endpoints The list of additions/modifications in catapult-rest. Endpoint urls, methods, parameters, and example responses.
Swagger The additions / modifications in catapult-rest formatted. Swagger file
SDK comments The SDK classes and methods should be described in the code. Comments format
SDK reference The SDK generated reference. Generated reference
Guides Articles explaining how to use the new feature step by step. Each article can include recommendations, best practices, and combination with other features. Writing a guide

History

Date Version
Jan 23 2018 Initial Draft
You can’t perform that action at this time.