Contributing

Here are common rules to keep a repository comprehensible as a whole — so that maintainers can stay aware of every element within the repository at all times. When a rule seems ambiguous, favor the interpretation that best preserves this comprehensibility.

---

Repository

Base files

Filepath	Description
./README.md	The first document. Description of the softwear, release schedule, quick start, provided api, etc.
./LICENSE	Includes Apache-2.0 or GPL-3.0-only and authors' names.
./CONTRIBUTING.md	The common entrypoint for all developers. Requirement, function, system diagram, public port, internal port, data layout, etc.
./.gitignore	As below.

# ./.gitignore
*.md
!README.md
!CONTRIBUTING.md

Issue

• Anyone can create issues at any time. Maintainers may clean these up at any time.
• tags

Label	Description	Color
bug	Something isn't working.	#d73a4a
controverse	What we should talk about.	#5B2F91
improvement	A way to improve the repository.	#259d63

---

Writing

This is for easy reading by human and computers.

• Use 4 spaces (0x20) for indentation.

Naming

• Single word naming is always best.
• In many cases, it is preferable to use singular names rather than plural ones.
• Abbreviations follow the same rule as others.
• State on the 1st line // This file includes untranslated text (ja). when needed.
• Follow the table below as much as possible, rather than the conventions of some stacks.

Category	Field	Rule	Description
directory	dirname	snake_case	Kebab-case is also good unless for script repos.
document	file	CamelCase	-
	outline	Capitalized with space	-
	sentence	Capitalized with space and .	-
script	file	snake_case	-
	variable	snake_case	And with kebab-case for 2 different degrees of relation.
data file	file	snake_case	-
	key	snake_case	Following the script variables.

Script

The following example uses Rust. When using a different stack, adapt it accordingly.

Dependency declaration

• Dependencies refer not only to third-party modules but to all callings defined outside of itself.
• Declare it not only in root (lib.rs), but each script file in its 1st block.
• Prohibit individual inline references below the declaration block.
• Order: core → alloc → std → crate → those with attributes (core → alloc → std → crate).
• For projects heap limitations might be useful, include a commented-out no_std declaration in the root file in advance.

// examples

// #![no_std]
extern crate core;
extern crate alloc;
extern crate std;
use core::{
    primitive::{u8, u64, usize, i64, str},
    fmt::{Display, Result, Formatter},
};
use alloc::{
    collections::{BTreeMap, BTreeSet},
    string::{String, ToString},
    vec::Vec,
};

#[cfg(test)]
use std::fs;

use crate::{
    list::{List, VariableList},
    debug_log,
}

Error

• Do not use std::error::Error implementations as they are not compatible with no_std.
• Define an item for each module (such as ListError), and wrap them in the public Error item (e.g., VariableListError::List(ListError)).

// examples

#[derive(Debug)]
pub enum ListError {
    OutOfBounds,
    NotExist,
}
#[derive(Debug)]
pub enum VariableListError {
    List(ListError),
    Compact,
}

impl Display for ListError {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result {
        write!(f, "{:?}", self)
    }
}

Literal quote

• slicable string: "" e.g., "", "ab"
• unslicable char: '' e.g., 'あ'

Comment

• Write an outer line DocComment for each public item.
• Write a DocTest for each public fun. Skip meaningless tests(e.g., Item:new) and comments.
• Write a DocTest when needed for each private fun.
• Inside functions, clearly state the intent with inline comments where necessary.

Test

• Write unit tests that is not duplicating with DocTest.
• Tests can depend on std::fs and the examples directory. Avoid inline dataset definitions.
• Names of test functions should follow the format {target}_{condition} (omit test_).
• When integration test, using the examples directory, in-memory mock implementations to verify exported functions.

Html

• formatting rule:
  • Do not insert a line break before a closing tag.
  • Insert a line break before the start of every tag.