Skip to content

Contributing

First off, thanks for wanting to contribute to the Spaced Repetition plugin!

Bug Reports & Feature Requests

  • Check the roadmap for upcoming features & fixes.
  • Raise an issue here if you have a feature request or a bug report.
  • Visit the discussions section for Q&A help, feedback, and general discussion.

Translating

Steps

To help translate the plugin to your language:

  1. Fork the repository.
  2. Copy the entries from src/lang/locale/en.ts to the proper file in src/lang/locale/ (i.e. fr.ts for French, or sw.ts for Swahili). The locale codes are IETF language tags.
  3. Translate,
  4. Then open a pull request,

Example

Sample en.ts file:

// English

export default {
    EASY: "Easy",
    SHOW_ANSWER: "Show Answer",
    DAYS_STR_IVL: "${interval} days",
    CHECK_ALGORITHM_WIKI:
        'For more information, check the <a href="${algo_url}">algorithm implementation</a>.',
};

Equivalent sw.ts file:

// Swahili

export default {
    EASY: "Rahisi",
    SHOW_ANSWER: "Onyesha Jibu",
    DAYS_STR_IVL: "Siku ${interval}",
    CHECK_ALGORITHM_WIKI:
        'Kwa habari zaidi, angalia <a href="${algo_url}">utekelezaji wa algorithm</a>.',
};

A part of that last one is uhh, Google translated, I have a working understanding of Swahili but not enough to write computerese lol.

Please note that:

  1. Only the strings(templates) on the right of the key should be translated.
  2. Text inside ${} isn't translated. This is used to replace variables in code. For instance, if interval = 4, it becomes 4 days in English & Siku 4 in Swahili. Quite nifty if you ask me.

Code

  1. Make your changes.
  2. Run pnpm dev to test the changes inside Obsidian.

  3. You could create symbolic links between the build files and the Obsidian vault, example:

    # remove existing files in the Obsidian vault
rm ~/notes/.obsidian/plugins/obsidian-spaced-repetition/main.js ~/notes/.obsidian/plugins/obsidian-spaced-repetition/manifest.json ~/notes/.obsidian/plugins/obsidian-spaced-repetition/styles.css
# use absolute paths
ln -s /home/stephen/obsidian-spaced-repetition/build/main.js /home/stephen/notes/.obsidian/plugins/obsidian-spaced-repetition
ln -s /home/stephen/obsidian-spaced-repetition/manifest.json /home/stephen/notes/.obsidian/plugins/obsidian-spaced-repetition
ln -s /home/stephen/obsidian-spaced-repetition/styles.css /home/stephen/notes/.obsidian/plugins/obsidian-spaced-repetition

  4. Document the "user-facing" changes e.g. new feature, UI change, etc.

  5. If your "business logic" is properly decoupled from Obsidian APIs, write some unit tests.
    • This project uses jest, tests are stored in tests/.
    • pnpm test
  6. Add your change to the [Unreleased] section of the changelog (docs/changelog.md).
    • The format is based on Keep a Changelog, TL;DR:
      • Added for new features.
      • Changed for changes in existing functionality.
      • Deprecated for soon-to-be removed features.
      • Removed for now removed features.
      • Fixed for any bug fixes.
      • Security in case of vulnerabilities.
    • You can also append a link to your GitHub profile, example:
      • Make flashcard text selectable [@st3v3nmw](https://github.com/st3v3nmw)
  7. Before pushing your changes, run the linter: pnpm lint
    • Format the code in case any warnings are raised: pnpm format
  8. Open the pull request.

Documentation

The documentation consists of Markdown files which MkDocs converts to static web pages. Specifically, this project uses MkDocs Material.

These files reside in docs/ in the respective language's folder. For instance, English docs are located in docs/en/.

The docs are served on https://www.stephenmwangi.com/obsidian-spaced-repetition/.

For small changes, you can simply open an pull request for merging (against the master branch). The changes will be live once a new release is made.

For larger diffs, it's important that you check how your docs look like as explained below.

Viewing Docs Locally

Initial Setup

  1. Create a virtual environment: python3 -m venv venv
  2. Activate it: . venv/bin/activate
  3. Install the required dependencies: pip install -r requirements.txt

Viewing

  1. Activate the virtual environment: . venv/bin/activate
  2. Serve the docs: mkdocs serve
  3. View your documentation locally on http://127.0.0.1:8000/obsidian-spaced-repetition/, any changes you make will reflect on the browser instantly.

Translating Documentation

  1. Create a folder for your language in docs/ if it doesn't exist. Use the language codes provided here.
  2. Add the code from (1) to the MkDocs configuration (mkdocs.yml - plugins.i18n.languages).
  3. Copy the files from the English (en) folder into the new folder.
  4. Translate then open a pull request.

Maintenance

Releases

Example using v1.9.2:

  1. Create a new branch: git switch -c release-v1.9.2
  2. Bump the plugin version in manifest.json and package.json (following Semantic Versioning).
    • Semantic Versioning TL;DR, given a version number MAJOR.MINOR.PATCH, increment the:
      • MAJOR version when you make incompatible API changes
      • MINOR version when you add functionality in a backwards compatible manner
      • PATCH version when you make backwards compatible bug fixes
    • If the new version uses new Obsidian APIs, update minAppVersion and versions.json to reflect this.
  3. Run pnpm changelog to update the CHANGELOG.

  4. Commit and push the changes:

    git add .
git commit -m "Bump version to v1.9.2"
git push --set-upstream origin release-v1.9.2

  5. Open and merge the PR into master.

  6. Locally, switch back to master and pull the changes: git switch master && git pull
  7. Create a git tag with the version: git tag 1.9.2
  8. Push the tag: git push --tags.
    You're all set! This GitHub action should pick it up, create a release, publish it, and update the live documentation.

  1. Check the Obsidian Tasks project which has excellent contribution guidelines. ↩