Developer Guides

Commit Standard Documentation

Brief Introduction

This documents should be referred, when contributers want to commit messages. It provides an easy set of rules for creating an explicit commit history, which makes the purpose of commits more specific.

The commit should be structured as follows:

<type>[optional scope][optional !]: <description>

Structural Elements

Contributers can use the following elements to replace type, scope and description.

Type

  • feat: Introduce a new feature to the codebase (this correlates with MINOR in Semantic Versioning).

  • fix: Patch a bug in your codebase (this correlates with PATCH in Semantic Versioning).

  • docs: Make changes in documentation.

  • style: Commit changes of code style, formatting, missing semicolons or whitespaces.

  • refactor: Make code changes that neither feat(add a new feature) nor fix(fix a bug).

  • perf: Commit changes that improve performance.

  • test: Add missing tests.

Scope(optional)

A scope may be provided to state the scope of commit’s influence, to provide additional contextual information and is contained within parenthesis.

For repository MatchBench, we can use “dataset”, “evaluator”, “model”, “pair_gen”, “trainer”, “utils” to state the scope of influence according the structure of MatchBench(ref).

Breaking Changes of !

Append a ! after the type/scope, which introduces a breaking API change (correlating with MAJOR in Semantic Versioning).

Description

The description contains a concise sentence of the applied changes. It has no specific standard, but we recommend to refer to the historical commits of corresponding repository.

Commit Examples

Here, several commit examples of project MatchBench are given for better understanding.

feat(model): add an EA model RREA

This means the commit adds an EA method to the submodule “model”.

fix(trainer): fix bugs in base_trainer.py

This means the commit is mainly about fixing bugs of base_trainer.py in submodule “trainer”.

style(evaluator): tweaked the code of metrics.py

This means the commit is mainly about code style tweak of metrics.py in submodule “evaluator”.

refactor(model)!: call 'load_source_target' function before training

This means we change the structure of all models in submodule “model”. When building the model, we should call the function ‘model.load_source_target()’ before training process. The exclamation mark “!” is added to draw the attention of Project Manager.

Reference

[1] https://www.conventionalcommits.org/en/v1.0.0/
[2] https://github.com/jochaes/Picturess/wiki/Commit-Standard
[3] https://github.com/anthoninCL/Flutter-I-MyTinder/wiki/Commit-standard

Pull Comment Standard Documentation

Brief Introduction

Anyone interested in our work is welcome to use Pull Request(P&R) to participate in. This documentation provides contributors guidelines for Pull Requests and the standard of P&R’s Comment.

Guidelines for Pull Requests

  1. Ask First. Please ask first Before embarking on any significant pull request(e.g. implementing features, refactoring code…).

  2. Licensing. By submitting a patch, you agree that your code will be licensed under the same hippie license that YOURLS uses, aka the “Do whatever the hell you want with it” license.

  3. Quality Requirements. Make sure your code adhere to Google Coding Standards. Otherwise, there will be unexpected results when generating code documents. Besides, if your P&R is about merging a new model, it is required to keep the result error within the allowable range.

P&R Comment Standard

When creating a new P&R(follow the docs), you should follow our P&R Comment Standard.

The Comment should include several parts: Introduction, Results, Reference,… Use Heading level 2 “##” in markdown for these heads.

The contents of these parts are described below.

  • Introduction: The main description of your work. For example, when merging a model, write down its main features, original papers and referred repository.

  • Results:(optional) When merging a model, record your reproduced results and original proposed results.

  • Findings:(optional) Interesting experimental findings can be shared in this part.

  • Required Packages:(optional) If your P&R requires extra packages, you should list required packages here and provide codes for install.

  • Other:(optional)

  • Reference: Urls of referred repository, relevant papers,…

P&R Comment Examples

It is recommended to refer to historical comment: pull23, pull24

Reference

[1] https://github.com/youkpan/YOURLS/wiki/Pull-Request
[2] https://github.com/ruc-datalab/MatchBench/pulls