Contributing to Forem

We expect contributors to abide by our underlyingCode of Conduct. All discussions about thisproject must be respectful and harassment-free.

Remember that communication is the lifeblood of any Open Source project. We areall working on this together, and we are all benefiting from this software.

It's very easy to misunderstand one another in asynchronous, text-basedconversations. When in doubt, assume everyone has the best intentions.

If you feel anyone has violated our Code of Conduct, you should anonymouslycontact the team with ourabuse report form.

Where to contribute​

Allissues labeledexternal contributors welcomeandbugare up for grabs. Please note that issues with theinternal team only label areinternal tasks that will be completed by a Foremcore team member.

• good first issueissues are meant for newer developers.

PRs without an associated issue may still be merged, but the core team willfocus on changes that solve existing issues. We strongly encourage creating anissue before working on a PR!

When in doubt, ask acore team member by mentioning uson the issue.

Documentation is almost always a great place to start contributing to a newproject. Forem is an Open Source, community-driven project. Therefore, providingand maintaining quality documentation is one of our most important jobs. You canfind more information in ourdocs guide!

Refactoring, which involves improving the code without modifying behavior,is a great place to help out! Generally speaking, you can rely on existing teststo ensure that your refactor doesn't introduce any unexpected behavior. If anarea isn't well tested, you might be asked to include a regression test withyour refactoring PR. Refactors can touch many files, so we encourage breakingbig changes into small PRs.

Fixing bugs is a super fast way to improve the experience for our users!When you're fixing bugs, we appreciate communication in a GitHub issue. If anissue exists, please claim that issue and link it in your PR, otherwise creatingan issue is the best first step! Be sure to surround bug fixes with ample tests;bugs are magnets for other bugs. Write tests around bugs!

Features tend to be subjective and might spur some debate. If you'd like topropose a new feature, please visitDiscussions to start adiscussion around a new feature (or chime in on a pre-existing discussion!).

How to contribute​

1. Fork the project and cloneit to your local machine. Follow the installation guide,for example, the Mac guide!
2. Create a branch with your GitHub username and the ID of theissue, for example:git checkout -b USERNAME/some-new-feature-1234
3. Code and commit your changes. Bonus points if you write agood commit message:git commit -m 'Add some feature'
4. Push to the branch:git push -u origin USERNAME/some-new-feature-1234
5. Create a pull requestfor your branch. 🎉

Contribution guidelines​

Create an issue​

Nobody's perfect. Something doesn't work? Something could be better? Check tosee if the issue already exists, and if it does, leave a comment to get ourattention! If the issue doesn't already exist, feel free to create a new one. Acore team member will triage incoming issues.

Please note: core team members may update the title of an issue to reflect thediscussion.

Issue claimers’ responsibility​

Once you’ve claimed an issue, you have a responsibility to work on that ticket in a reasonably timely fashion. If you don’t have time to work on it, please unclaim it so someone else may work on it.

If there’s no sign of progress on a particular claimed issue for a week or two, we may ask you to relinquish the issue claim to open it up to other contributors.

If you’ve claimed an issue and it’s taking a long time (weeks) to code, keep everybody updated by posting comments on the issue. If you don’t provide regular updates, and you don’t respond to a request for a progress report, we may open it back up to other contributors.

Any pull requests older than 90 days will be closed. Exceptions can be made for pull requests that have active review comments, or that are awaiting other dependent pull requests. Closed pull requests are easy to recreate, and little work is lost by closing a pull request that subsequently needs to be reopened. We want to limit the total number of pull requests in flight to:

• Maintain a clean project
• Remove old pull requests that would be difficult to rebase as the underlying code has changed over time
• Encourage code velocity

As always, more communication is better than less communication! We are all humans trying to work together to improve the community. Always be kind and appreciate the need for tradeoffs. ❤️

Please include tests​

Some areas of the project could use updated tests, and new features shouldalways include test coverage. Feel free to read our testing section for guides, such as the one forFrontend Tests.

Code quality​

We useCode Cov to incentivize us to write tests and increase coverage.

We deliver the coverage metrics directly into the PR to promote more code coverage, especially in pull requests where new features and bug fixes commonly occur.

We encourage you to always increase the code coverage with any new feature or bug fix.

Consider accessibility in UI changes​

If the change you're proposing touches a user interface, include accessibilityin your approach. This includes things like color contrast, keyboardaccessibility, screen reader labels, and other common requirements. For moreinformation, check out theForem Accessibility docs page.

Please use inclusive language​

Inclusion and respect are core tenets of ourCode of Conduct. We expect thoughtful languageall the way down to the code. Some technical metaphors are alienating ortriggering. We ask that contributors go the extra mile to submit code which isinclusive in nature.

If you unintentionally use language deemed harmful, there is no shame. We willwork together to find a better alternative. Being thoughtful about language alsoencourages more thoughtful code!

Create a pull request​

• Try to keep the pull requests small. A pull request should try its very bestto address only a single concern.
• For work in progress pull requests, please use theDraft PRfeature.
• Make sure all tests pass and add additional tests for the code you submit.More info here.
• Document your reasoning behind the changes. Explain why you wrote the code inthe way you did. The code should explain what it does.
• If there's an existing issue, reference to it by adding something likeReferences/Closes/Fixes/Resolves #123, where 123 is the issue number.More info here.
• Please fill out the PR Template when making a PR.
• All commits in a pull request will be squashed when merged.

Please note: a core team member may close your PR if it has gone stale or if wedon't plan to merge the code.

Pull request reviews​

All community pull requests are reviewed by our core team.

• All contributors must sign the CLA.
  • You will be asked fromCLAassistant. Youcan confirm the signing status and signed content athttps://cla-assistant.io/forem/forem.
• All required checks are expected to pass on each PR.
  • In the case of flaky or unrelated test failures, a core team member willrestart CI.
• We require 2 approvals from core team members for each PR.
• Requested Changes must be resolved (with code or discussion) before merging.
• If you make changes to a PR, be sure to re-request a review.
• Style discussions are generally discouraged in PR reviews; make a PR to thelinter configurations instead.
• Your code will be deployed shortly after it is merged.

A note on "force pushing"​

After you submit your pull request, one of the members of the core team willreview your code.

Please avoid force pushing unless you need to rebase with the main branch.

If feedback is provided, any changes should be contained in new commits. Pleasedon't force push or worry about squashing your commits.

Force pushing (despite being useful) has some drawbacks. GitHub doesn't alwayskeep the review history, which results in lost context for the reviewers.

We squash every PR before merging, so there is no need to force push!