Skip to content

Latest commit

 

History

History
137 lines (107 loc) · 6.72 KB

CONTRIBUTING.md

File metadata and controls

137 lines (107 loc) · 6.72 KB
Raw

ApostropheCMS Contribution Guide

Interested in contributing to ApostropheCMS? Excellent! 🙌

We really appreciate your interest and value your time. The guidelines below are meant to make the most of your time and work. Your contributions help maintain ApostropheCMS as (in our opinion) the best Node CMS in the universe.

In addition to contributing to the project, you can also join the growing community on Discord for discussion, core development updates, and help as you build with Apostrophe. There are also Github Discussions and Stack Overflow.

Code of Conduct

All contributors and community members are expected to abide by the Code of Conduct. In short, be excellent to one another, respect everyone's contribution, and never harass anyone for any reason. Alert the core team at [email protected] if you find someone failing to abide by the Code of Conduct.

How can I contribute?

Reporting Bugs

If you come across a bug, please submit an issue in the GitHub repo. Be sure to search the existing issues first and make sure it hasn’t already been logged. If it has, add a comment with any information you think might help resolve it.

If it hasn’t, check:

  • Are you on the lastest minor version of the Apostrophe modules you're using?
  • Is your dev environment up to date? Primarily this means a LTS version of Node.js and MongoDB 3.x or 4.x.
  • Is this related to project code? Can you reproduce it in a minimal test case, without the rest of your project code? If it might be specific to your project, asking a question is a better first step (see below).

If the answer to those is "yes," please submit a bug issue. There is a bug issue template when you create one in Github to help with that.

Bonus: Although not required, if you write a test that reproduces the bug you found, and submit that failing test as a PR… well, we might even send you some swag 😉.

If you're not sure whether it's a bug or a problem in your code, you can post questions and find answers to support questions about ApostropheCMS in StackOverflow or Discord.

Suggesting a Feature or Enhancement

We track feature requests and larger scale enhancements within the GitHub repository. After you search existing issues to confirm your idea is new, please submit your idea as a new issue. Remember to include details that articulate the current functionality and how this enhancement will improve or build upon that. Again, there's an issue template to help you.

Fixing Bugs or Submitting Enhancements

PRs to resolve existing issues are fantastic. Two good places to start are the "help wanted" and "good first issue" issues.

Please note that if you are using Windows for development, we strongly recommend using Windows Subsystem for Linux (WSL) both for development on the core Apostrophe modules and developing your own applications.

If you’ve perused our open issues labeled bug and decide to work to resolve one, or you’ve got a new feature that you’d like to commit to the core project, please keep these things in mind:

  1. Most substantial changes will require tests. For examples of back-end unit tests, look here at the test folder of the apostrophe module. This level of coverage is expected for backend features that aren't already covered by a test. If you are submit bug fix, please do include a test that reproduces the issue.
  2. Make sure existing tests pass. Run npm test to run the tests, including the code linters.
  3. Enhancements should include documentation and include implementation details were applicable. For Apostrophe core, that should be in the main documentation and for other modules, add it in their README files (unless the README directs you elsewhere).

Improving documentation

The documentation repo is public and we appreciate contributions. The core maintainers know Apostrophe very well, but that can make it hard to see where the gaps in documentation are. Please open issues there letting us know (nicely, please). Even better, submit a pull request documenting something and you'll be helping many developers going forward.

Even typo fixes are great!

Share the Love

Authoring blog posts, giving talks at a meet-up, or otherwise sharing experiences using ApostropheCMS help spread the word. When you launch a site on ApostropheCMS, ping us in Discord or on Twitter. We love a good success story.

Should I make a new npm module?

Great question. If it's not a bug fix or an improvement to the core UI, it often doesn't belong in the core apostrophe npm module. For instance, our SEO functionality is in the separate @apostrophecms/seo npm module.

Some tips:

  • You can take any Apostrophe project module (modules/my-module), move that to the root of its own repository and package it up as an npm module. It should just work, as long as all of your dependencies are part of the module. Set peerDependencies if this will rely on a module that isn't directly used in your code.
  • Please do not use the apostrophe- prefix for your module, or the apos- prefix for your styles without consulting the core team. This was an Apostrophe 2 convention, but by reserving these for the official Apostrophe modules, we can maintain clarity for new Apostrophe developers regarding which modules the core team is committed to maintaining.
    • To avoid confusion, you can pick your own prefix. It's good practice to use a prefix so that you don't conflict with project-level modules.
  • Add apostrophecms to your keywords in package.json to help people find your module.