Skip to content

Latest commit

 

History

History
184 lines (128 loc) · 6.21 KB

dev.md

File metadata and controls

184 lines (128 loc) · 6.21 KB
Raw

Developing Documentation

Philosophy

Code Quality Matters! User Experience Matters!

Code Quality Matters! User Experience Matters!

Code Quality Matters! User Experience Matters!

  • Keep it Simple, Stupid, Clear, & Clean.

  • No Over-Engineering. Don't do things for the sake of doing things. Every technical decision has to be made for specific reasons and leads to gains(e.g. improves readability, maintainability user experience, etc).

  • Premature Optimization is the Root of All Evil. Good enough is perfect. Let it grow first and optimize it later on if necessary.

  • Iterative Mindset. Don't try to do everything in one go. Keep every change small & clear.

Workflow

Forking Workflow is used. To contribute, please work on a forked repo and create a PR from the forked repo to the develop branch of the main repo.

The main repo will have 3 branches:

  • main: The latest version that is released.
  • develop: The latest version that is being worked on.

Set Up Development Environment

The development requires Python 3.9. Dependencies for development will be managed by Pipenv.

To set up the development environment, go to the project root directory and

  1. Install dependencies with Pipenv and use Pipenv shell as the shell environment.

    pipenv install -d
pipenv shell

  2. Install Git hooks with pre-commit in the Pipenv shell so that the Python formatter black will be triggered for each commit.

    pre-commit install

Set up Automated Testing with Github Action

This project comes with a Github Action workflow script to automatically run test cases on a new git push.

To enable this feature,

Then the Github Action will be triggered on each push to your own fork project.

Code Style Guide

Google Python Style Guide is adopted.

Git Commit Style

py-vsys's commit style is a simplified version of Angular Commit style.

Commit Format

<type>: <short summary>
  │               │
  │               └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: build|docs|feat|fix|refactor|test|chore

Commit Type must be one of the following:

  • build: Changes that relate to dependencies, CI, etc
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing tests or correcting existing tests
  • chore: Other trivial changes

Branch & PR Naming Convention

A branch and the PR comes from it should be small(i.e. contains small-scale changes for only 1 aspect).

The naming convention for branch

type/short-summary-in-lower-case
  │               │
  │               └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: build|docs|feat|fix|refactor|test|chore

The naming convention for PR

type: short summary in lower case
  │               │
  │               └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: build|docs|feat|fix|refactor|test|chore

For example, say we would like to add the branch naming convention to the documentation. The branch name should look like

docs/add-branch-naming-convention

The PR should look like

docs: add branch naming convention

Github Issue Naming Convention

The naming convention for Github issues conforms to the PR one.

type: short summary in lower case
  │               │
  │               └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: build|docs|feat|fix|refactor|test|chore

For example, to suggest adding test cases, the issue name should look like

test: add test cases for XXX

To file a bug, the issue name should look like

fix: XXX is incorrect

Doc String Guide

Doc string is a must for wherever it is applicable (e.g. module, class, function, method, etc) so that API references documentation can be auto-generated out of it.

py-vsys follows Google Style and borrows from Golang the idea of starting the commentary always with the name of the object you'd like to comment.

Below is an example.

@abstractmethod
def issue(self, by: acnt.Account, description: str = "") -> Dict[str, Any]:
    """
    issue issues a token.

    Args:
        by (acnt.Account): The action taker.
        description (str): The description of this action. Defaults to "".

    Returns:
        Dict[str, Any]: The response returned by the Node API.

    Raises:
        NotImplementedError: Left to be implemented by the sub class.
    """
    raise NotImplementedError

For folks using VSCode, the plugin Python Docstring Generator is recommended to quickly generate the doc string template.