Skip to content

CONTRIBUTING.md

Latest commit

聽

History

History
99 lines (67 loc) 路 4.32 KB

CONTRIBUTING.md

File metadata and controls

99 lines (67 loc) 路 4.32 KB
Raw

Contributing to obsidian.nvim

Thanks for considering contributing! Please read this document to learn the various steps you should take before submitting a pull request.

TL;DR

  • Start an issue to discuss the planned changes
  • To submit a pull request
    • Start developing your feature in a branch
    • Make sure that your codes complies the obsidian.nvim code style, run make chores
    • The PR should contain
      • The code changes
      • Tests for the code changes
      • Documentation for the code changes (in the code itself and in the README.md)
      • CHANGELOG.md entry for the code changes

Details

Note: we automate tedious tasks using a Makefile in the root of the repository. Just call make to see what you can do, or make chores to run the most important tasks on your code. You can override some parts of the Makefile by setting env variables.

Local development with LuaLS and plenary.nvim

If you're using the Lua Language Server (LuaLS) you'll probably want to add plenary.nvim as a workspace library since we rely heavily on plenary throughout the codebase. You can do this by adding a .luarc.json configuration file that looks like this:

{
  "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
  "runtime.version": "Lua 5.1"
}

Make sure that the path there to plenary is correct for you.

Keeping the CHANGELOG.md up-to-date

This project tries hard to adhere to Semantic Versioning, and we maintain a CHANGELOG with a format based on Keep a Changelog. If your PR addresses a bug or makes any other substantial change, please be sure to add an entry under the "Unreleased" section at the top of CHANGELOG.md. Entries should always be in the form of a list item under a level-3 header of either "Added", "Fixed", "Changed", or "Removed" for the most part. If the corresponding level-3 header for your item does not already exist in the "Unreleased" section, you should add it.

Formatting code

TL;DR: make style

Lua code should be formatted using StyLua. Once you have StyLua installed, you can run make style to automatically apply styling to all of the Lua files in this repo.

Linting code

TL;DR: make lint

We use selene to lint the Lua code and typos to catch typos. Once you have selene and typos installed, you can run make lint to get a report.

Checking types

TL;DR: make types

We use lua-ls to check the type annotations in the lua code. Once you have lua-ls installed, you can run make types to check types.

Newly written code should have type annotations.

Running tests

TL;DR: make test

Tests are written in the tests/ folder and are run using mini.test. The make command will download the dependencies for you. For a reference of using mini.test, see this. We are currently in the process of migrating from busted style tests to mini's style, if you are writing test for a new module, prefer the mini style.

Building the vim user documentation

TL;DR: make user-docs

The Vim documentation lives at doc/obsidian.txt, which is automatically generated from the README.md using panvimdoc. Please only commit documentation changes to the README.md, not doc/obsidian.txt.

However you can test how changes to the README will affect the Vim doc by running panvimdoc locally. To do this you'll need install pandoc (e.g. brew install pandoc on Mac) and clone panvimdoc (e.g. git clone git@github.com:kdheepak/panvimdoc.git ../panvimdoc).

This will build the Vim documentation to /tmp/obsidian.txt.

Building the vim API documentation

TL;DR: make api-docs

The API docs lives in doc/obsidian_api.txt and is generated from the source code using mini.docs. It is automatically generated via CI.