Contributing to Marp project
Thank you for taking the time to read how to contribute to our project! This is the basic guideline for contributing to Marp team owned projects.
You can start contributing our project in several ways: improve docs, report bug, request feature, writing code, and so on.
Depending on the project you want to contribute, it might have additional guidelines you should follow at that repository. Please also check the guideline per repository.
ℹ️Would you the first time to contribute OSS? Open Source Guides might help you.
At first, you should search for similar issues before reporting your issue. It may have already been discussed or resolved in the other issue.
org:marp-team is:issue [keyword] is useful to search issue from across our projects.
If you could not find out similar issue, you can create new issue. Please not contain multiple reports in one issue. It should have only one theme.
ℹ️Some projects have consisted of multiple packages created by marp-team. If you know which project causes an issue, please report the issue to that repo.
Keep in mind that GitHub issue tracker is not a support forum. You should not expect an answer to such a question at GitHub. You can use StackOverflow if you want.
Feature request is welcome because it could give feedback to us.
However, we have to take a moment to judge whether fitting to the project aim and scope. We require clear benefit and strong incentive to work for the request because each our projects should keep simple and smart. A created issue would serve as a table for discussion.
⚠️Did you find a security vulnerability? Report directly to email@example.com instead of opening a new issue.
Currently, we don't have a default issue template. But to assist in finding the bug by committer rapidly, it is good to describe these:
- Expected behavior and actual behavior
- Necessary steps and resources to reproduce bug
- Occurred environment (e.g. the version of OS, browser, Node.js)
You can submit pull request if you have fixed or added useful something to our projects.
Indicate related issue(s) in description of PR. In many cases, the created PR should already have related problems. GitHub can close issue automatically by keyword.
Keep code styling. We are using yarn package manager, Prettier formatter, and linters for each language. CI build would fail when using the wrong format/style. It could fix by
yarn format --writeand
yarn lint:[lang] --fixin most projects.
Maintain tests. We need to fill code coverage by writing meaningful tests. In many projects, we are setting a threshold of global line coverage to 95%. You could measure coverage in local by running
These are tasks for maintainer, and usually comitter doesn't have to worry.
- If there is CHANGELOG.md in a working project, the maintainer has to update it after (or while) merge PR. We're adopting the format based on Keep a Changelog.
The core maintainer can release package or product of marp-team projects.
⚠️You have to use
npmin a release process, and NEVER use
Basically we are following Semantic Versioning.
v0.0.x as the pre-release version. Against the spec of semver, it may update only patch version until reach to the stable implementation even if it has some breakings or incompatible changes.
Maintainer should mark
v0.0.x as "Pre-release" in GitHub release page.
We have automated bumping version with
version npm script in many repositories.
If it is defined in
npm version [major|minor|patch] at latest
master branch to bump version. In many cases, it would add the version tag and update CHANGELOG.md.
After than, push master branch and tag by
git push && git push --tags. Please update GitHub release by taking copy of change logs from updated CHANGELOG.md if possible.
Publish to npm
Several repository provide npm package. The core maintainer can publish package to npm after bumping version.
For the security reason, we are not planned to automate publishing. We require two-factor authentication to publish.
ℹ️Maintainer should configure to check code styling and tests again when running important commands through
preversion(bumping version) and
prepack(publish to npm).