d-eniz_jupymd/CONTRIBUTING.md

Contributing to JupyMD

Thank you for your interest in contributing! Please follow the following guidelines to keep the project maintainable.

General etiquette

Remember that this is a community driven project, maintained in people’s free time. Please be patient and respectful when waiting for a response.

Code quality & "vibe coding"

If you don't have experience with the Obsidian API, we ask you to refrain from opening pull requests. Your contributions through discussions in issues are just as valuable as pull requests.

Asking maintainers to spend time reviewing "vibe coded" pull requests which you haven't spent time on yourself is unacceptable. Current AI tools lack context on the Obsidian API and the Obsidian plugin guidelines, and produces unreliable code.

Commits

• Use conventional commits. Make sure your commit messages are descriptive.
• Keep commits to one logical change at a time. Try to avoid large commits.
• Make sure your commits leave the project in a working state. Your changes should not break existing features.
• Don't bump versions or edit the manifest file.
• Don't commit unnecessary files or make unnecessary changes.

Pull requests

1. Before working on a PR, discuss the topic in issues first. Make sure this discussion is meaningful and give it some time for other people to read the issue. This is a good way of learning more about the problem at hand, and also prevents multiple people submitting a PR for the same issue.
2. Keep PRs small and focused, tackle one problem/feature/topic at a time.
3. Describe your problem clearly and extensively, point to any issues where this has been discussed. Describe your code and how you have tackled the problem.
4. If your PR makes a visual change, add screenshots showing the change.
5. Aim to make PRs ready to merge.
6. If you are requested to make changes, do not completely disregard your previous commits and start over.

It is disrespectful to ask for a review on a PR which you have not reviewed yourself.

Draft pull requests

You are allowed to submit a draft PR, given you tag it appropriately. If your PR is almost ready, but there is a small section that you need help with, you may create a draft PR. If you’re unsure how to approach the problem your PR will focus on, it’s best to start a discussion in issues first. Draft PRs are not exempt from any of the guidelines described above.

Notes on maintainability

It is a good idea to have a general understanding of the project workflow and the Obsidian API before editing the codebase. You are not expected to understand every detail of the codebase, however if you are unfamiliar with the codebase or the Obsidian API it would be a better idea to raise and issue rather than trying to tackle the problem yourself with a PR.

It is important that we keep the codebase tidy and easy to understand. Not only does this make it easier for new contributors to learn the codebase, it also makes maintenance and spotting problems easier.

If you choose to use AI, make sure the generated code makes sense within the context of the general codebase.