Skip to content

Latest commit

 

History

History
160 lines (111 loc) · 6.1 KB

contributing.mdx

File metadata and controls

160 lines (111 loc) · 6.1 KB
Raw
title description
Contributing
Contributing to Mintlify

Overview

Thank you for your interest in contributing to Mintlify! There are multiple ways to contribute, please feel free to ask for help on Slack or GitHub.

Everyone who contributes to Mintlify is expected to read and follow the Code of Conduct. We expect everyone in our community to be welcoming, helpful, and respectful.

We also encourage anyone interested in contributing to check out all the information here in our contributing guide, especially the contribution guidelines and standards.

We greatly appreciate your help! 💚

Ways to contribute

Make sure you have familiarized yourself with Development.

  • Before opening a new issue, check if a similar issue or pull request already exists.
  • Create a pull request with your changes and write a summary, as well as a test plan for the changes.
  • When the PR is marked as ready for review, the engineering team will be notified and a contributor will handle it.

Contribution Tools

We are using contribution tools to simplify following our standards.

Staged files are linted and formatted automatically on `pre-commit`.
  • eslint - Analyzes code using multiple linting configurations/rules.
  • prettier - Used to format text files.
  • husky - Used to set up and manage git hooks.
  • lint-staged - Runs eslint/prettier against staged files.
  • pre-commit - Validates and cleans up git commits by running the above tools automatically, using a git hook.

Manual usage

It is possible and sometimes helpful to run the contribution tools manually.

  • linting with eslint: yarn lint
  • formatting with prettier: yarn format
  • install git hooks (triggered automatically on yarn install): yarn prepare
  • run lint-staged to check before committing and triggering the pre-commit git hook: yarn lint-staged

Visual Studio Code

To format the code as you make changes you can install the Prettier - Code formatter extension.

Add the following to your User Settings to run prettier on save.

"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode"

Troubleshooting

If you encounter issues when trying to commit, it could be because one of the tools fails to conclude successfully.

`lint-staged` is using `--max-warnings 0`, which does not allow any warnings in staged files.

If warnings and errors cannot be resolved in any way, or if refactoring old code, that includes warnings, one of the following workarounds can be used.

  • Use --no-verify.
git commit --no-verify
  • Disable eslint rule for line/file.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const x: any = {};
If you need help or if you encounter errors or warnings, don't hesitate to ask a question on [Slack](https://mintlify.com/community) or [GitHub](https://github.com/mintlify/mint/issues).

Contribution guidelines and standards

Contributors of Mintlify are expected to:

  • Read and follow the Code of Conduct.
  • Read and follow the Mintlify code style.
  • Code contribution guidelines are incomplete while Mintlify is still being developed and evolving, and may change later.

Style

Projects should contain an eslint and a prettier config. Please refer to these files for style rules.

Shared configurations can be found in this [repository](https://github.com/mintlify/config).

Git branching model

We are following git flow when creating branches and are doing back merges from main to dev to reduce the overhead of PR's. Please refer to the following rules when creating or merging branches:

Feature branches

  • Based on dev
  • After finishing your work, open a PR, that targets main
  • Merge to main after approval
  • Can be squashed

Release branches

  • Based on dev
  • After finishing the release, open a PR, that targets main
  • Merge to main after approval
  • Don't squash, as it messes with git history and causes conflicts
  • Merge main to dev after successfully closing the PR

Hotfix branches

  • Based on main when the bug is on main, based on dev when the bug is exclusively on dev
  • After finishing the fix, open a PR, that targets the base branch.
  • Merge to target branch after approval
  • Can be squashed
  • Merge main to dev after successfully closing the PR, if the PR is based on main

Squash

  • Whenever you want to squash commits, make sure that the branch is immediately deleted afterwards and not merged to anything else as it can cause conflicts on all changed files.
  • When merging release branches don't squash old commits or commits, that have been squashed already

Rebase/Force-push

  • This means rewriting git history. Can be used on feature branches, if you are working alone on it and nobody is reviewing it already.
  • Only do this if you are certain that nobody pulled this branch, because their branch will be broken and unusable and it means potentially loosing changes or having a lot of conflicts.

Links