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¶

The plugin has been translated into the following languages by the Obsidian community 😄.

Arabic / العربية
Chinese (Simplified) / 简体中文
Chinese (Traditional) / 繁體中文
Czech / čeština
German / Deutsch
Italian / Italiano
Korean / 한국어
Japanese / 日本語
Polish / Polski
Portuguese (Brazil) / Português do Brasil
Spanish / Español
Russian / русский

Steps¶

To help translate the plugin to your language:

Fork the repository.
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.
Translate,
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:

Only the strings(templates) on the right of the key should be translated.
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¶

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

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

This can be coupled with the Hot Reload plugin

Document the "user-facing" changes e.g. new feature, UI change, etc.
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
Add your change to the [Unreleased] section of the changelog (docs/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)
Before pushing your changes, run the linter: pnpm lint
- Format the code in case any warnings are raised: pnpm format
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¶

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

Viewing¶

Activate the virtual environment: . venv/bin/activate
Serve the docs: mkdocs serve
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¶

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

Maintenance¶

Releases¶

Example using v1.9.2:

Create a new branch: git switch -c release-v1.9.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.
Run pnpm changelog to update the CHANGELOG.

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

Open and merge the PR into master.
Locally, switch back to master and pull the changes: git switch master && git pull
Create a git tag with the version: git tag 1.9.2
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.