Skip to content

Latest commit

 

History

History
147 lines (105 loc) · 8.9 KB

CONTRIBUTING.md

File metadata and controls

147 lines (105 loc) · 8.9 KB
Raw

Contribution tips and guidelines

👍🎉 We're excited you want to contribute! Read on! 🎉👍

Pull requests • Tackling issues • Reporting bugs • Maintainers • Labels

Pull requests are always welcome

Not sure if that typo is worth a pull request? Found a bug and know how to fix it? Do it! We will appreciate it. Any significant improvement should be documented as a GitHub issue before anybody starts working on it.

We are always thrilled to receive pull requests. We do our best to process them quickly. If your pull request is not accepted on the first try, don't get discouraged! We'll work with you to come to an acceptable solution.

If you're new to GitHub or open source you can check out this free course on how to contribute to an open source project.

Disclaimer: Contributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.

Running tests

Before submitting your PR, make sure that all new and previous tests pass and that coverage has not decreased:

npm run test-coverage

Adding tests

Marko makes use of a directory based test structure. A simplified view is below:

test/
 ⤷ autotests/
    ⤷ render/
      ⤷ attrs/
      ⤷ for-tag/
        ⤷ expected.html
        ⤷ template.marko
        ⤷ test.js
      ⤷ nested-tags/
      ⤷ while-tag/
 ⤷ render-test.js

The render-test.js file will run and read all the directories under autotests/render and for each directory (attrs, for-tag, etc.) it will run test.js, render template.marko and assert that it is equivalent to the content of expected.html.

In most cases you'll simply copy a directory and modify it to add a new test. And we're here to help if you have any questions or need to do something fancy.

Tackling an existing issue

Comment on the issue and let us know you'd like to tackle it. We'll assign you to the issue so that we don't duplicate effort.

If for some reason you aren't going to be able to complete the work, let us know as soon as you can so we can open it up for another developer to work on.

Here's some to get started with:

  • bite-sized issues: great for new contributors
  • help-wanted issues: won't be tackled in the near future by the maintainers... we need your help!
  • un-assigned issues: open issues that no one has claimed... yet

Reporting bugs and other issues

A great way to contribute to the project is to send a detailed report when you encounter an issue.

Check that our issue database doesn't already include that problem or suggestion before submitting an issue. If you find a match, you can use the "subscribe" button to get notified on updates. Rather than leaving a "+1" or "I have this too" comment, you can add a reaction to let us know that this is also affecting you without cluttering the conversation. However, if you have ways to reproduce the issue or have additional information that may help resolving the issue, please leave a comment.

We have an ISSUE_TEMPLATE that will populate your textarea when you go to open an issue. Use the relevant section and remove the rest.

Please provide as much detail as possible.

Reporting security issues

If you discover a security issue, please DO NOT file a public issue, instead send your report privately.

Security reports are greatly appreciated and we will publicly thank you for it. We currently do not offer a paid security bounty program.

Maintainers

Labels

Once you post an issue, a maintainer will add one or more labels to it. Below is a guideline for the maintainers and anyone else who is interested in what the various labels mean.

Type

Every issue should be assigned one of these.

  • bug: A bug report
  • enhancement: A feature request
  • question: A question about how to use Marko
  • docs: An issue about documentation

Scope

What part of the Marko stack does this issue apply to? In most cases there should only be one of these.

  • parser: Relates to htmljs-parser
  • compiler: Relates to the compiler (server only)
  • runtime: Relates to the runtime (isomorphic/universal)
  • core-taglib: Relates to custom tags that ship with Marko
  • components: Relates to marko-components
  • tools: Relates to editor plugins, commandline tools, etc.

Difficulty

Indicates a very large or very small issue. Not required.

  • bite-sized: An issue that would be great for new contributors to tackle
  • epic: A large change that will take some time and likely have sub-issues

Status

In many cases, additional actions should be taken when applying one of these.

  • resolved: The question was answered, the bug was fixed, or the feature was implemented. Close the issue.
  • confirmed: This is indeed a bug, or the feature has been fleshed out and should be implemented.
  • help-wanted: This is not something on the main roadmap, but we'd love for someone in the community to tackle it
  • invalid: This was user error, not a bug. Close the issue.
  • duplicate: Someone has already posted the same or a very similar issue. Reference the original issue and close this issue.
  • wontfix: This is not a bug, but intended behavior, or this feature will not be implemented. Close the issue.
  • needs-clarifying: More information is needed to reproduce the bug. Ask for more information. If no reply is received within a week, the issue should be closed.
  • see-other: This bug is actually due to an issue with another library. If there is an existing issue for that library link to it, if not create one and link to it. Close the issue.