Skip to content

Latest commit

 

History

History
182 lines (129 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

182 lines (129 loc) · 5.79 KB
Raw
title author
How to contribute
ryu-raptor

日本語を利用する人が主に利用するため，日本語によるコントリビューションガイドを示します．

ドキュメントの書き方

  • 特に理由がない限り，Markdownで記述してください．拡張子は.mdでお願いします．

  • このソフトウェアの目的上，和文と欧文の間にアキを入れる必要はありません（四季で処理すればよいですからね）．

  • front-matterはできればつけてください

    • titleを少なくともつけてください
    • authorは文字列または文字列の配列です
      • 著者表示は任意です
      • 編集（誤字脱字の修正でも）した方はだれでもauthorに追加できます

  • タイトルはfront-matterにあるので，改めてH1要素で記述する必要はありません

  • 章はH1から始めてください（README.mdのように）

issueの立て方

issueは基本的に

  • バグの報告
  • 機能の提案
  • 機能の修正

を議論する場所とします．

バグの報告

バグだと思われる場合は，次の情報を記載してください．

  • 入力したテキスト
  • 出力されたテキスト
  • 期待していた挙動，もしくは何がおかしいか

issueの例

  • 入力テキスト
LaTeXはアキを入れてくれます.
  • 出力テキスト
 LaTeX はアキを入れてくれます.
  • 期待していた挙動 文頭と文末にアキは入らない．

機能の提案

機能の提案には次の情報を添えてください．

  • 入力テキスト

  • （可能であれば）予定しているコマンドラインオプション

  • その機能により得られるであろう出力テキスト

  • 出力テキストの説明

  • 機能が必要な理由

  • 可能であれば詳細な仕様を記述してください．

README.mdの「これからするようになること」に記載されている内容の場合は，「機能が必要な理由」は不要です．

「直接プルリクじゃだめか」についてですが，万が一取り込まれなかったときにダメージがでかいのでおすすめしません． また，他の方が手伝ってくれるかもしれませんので，一旦issueを立てることをおすすめします．

issueの例

  • 入力テキスト
アルファ/ベータ線
  • 予定しているコマンドラインオプション
aki --slash-aki <file> ...
  • その機能により得られるであろう出力テキスト
アルファ / ベータ線

  • 出力テキストの説明 スラッシュをbetweenルールで処理します．

  • 機能が必要な理由 スラッシュの前後にアキを入れる慣習があるため． オプションで指定するのは，アキを入れない慣習もあるため． アキを入れる場合として，スラッシュが改行位置を示す符号として使われたときが挙げられる．

機能の修正

現在の仕様では不都合が生じる場合は，修正を提案してみてください． 添付する情報は「機能の提案」で述べたものに加え

  • 現在の仕様とどう異なるのか

についても説明してください．

ブランチモデル

WIP

README.mdの編集

著者表示

front-matterのauthor欄に名前（源氏名など）を入れることをおすすめします．その場合，配列に変更してください．

---
title: 四季マニュアル
author: ryu-raptor
---

を

---
title: 四季マニュアル
author:
    - ryu-raptor
    - あなたの名前
---

にしてください．

README.inserted.md

README.mdを編集した場合はプルリクエスト前でいいですので，四季でスペースを挿入したREADME.inserted.mdを生成してコミットしてください．

現在のバージョンの挙動を確認してもらうためのサンプルとして機能させたいため，よろしくおねがいします．

生成するには，プロジェクトルートで次のコマンドを実行します（v1.1-0）．

aki README.md -o README.inserted.md

バージョン1.3からはこちらでお願いします．

aki -e README.md -o README.inserted.md

コードの編集

インデントとスペース

4スペース = 1インデント

タブ派の場合はgitの設定でタブをスペースに自動変換するようにしてください．

参考

演算子とオペランドの間にはスペースを挟みます．

面倒ですが，よろしくお願いいたします．

OK: i = 1 + 1
NG: i=1+1

テーブルは配列と辞書を混合しないように

特に関数の引数として受け取るテーブルや，shiki名前空間から直接アクセスできるテーブルでは厳守してください． 命名規則は特に無いですが，どちらを期待しているかを明記すると混乱せずに済むと思います．

NG: geniusTable = { 1, 2, 3, hoge = true, foobar = false }
OK: numbers = { 1, 2, 3 }; options = { hoge = true, foobar = false }

できるだけデータを引数から渡すようにしてください

Luaといえどもグローバル変数は混乱の元です．

例えばshiki.pfinder関数はバージョン1.3からescape_instanceを受け取るようになりました．

このように引数から渡すことで混乱を抑えられます．

どうしても引数から渡すべきでないと判断できるなら，モジュールとして提供してください． たとえばshiki.configモジュールはその例です．