Skip to content

Latest commit

 

History

History
68 lines (43 loc) · 6.5 KB

CONTRIBUTION.md

File metadata and controls

68 lines (43 loc) · 6.5 KB
Raw

Contribution

Your Contribution is Valued

If you find something in our documentation that can be improved, please let us know by creating an issue in our issue tracker.

After creating the issue, you are encouraged to make the changes and submit a Pull Request (PR), following all the Guidelines on this page.

Pull Requests (PR)

Please follow the guidelines below when submitting a PR.

Guidelines for pull requests

  • KISS - Keep It Simple, Stupid. Fewer changes per PR are better.
  • Respect Notepad++ User Manual style.
  • It is best if there is an open issue before making changes and submitting a PR, so that you can ask whether your idea is worth incorporating before spending the effort on.
  • You will need to create a fork to make changes. Create a new branch in your fork for each PR, keeping each PR independent of others you submit.

If these guidelines and style guide are not followed, or if the reviewers otherwise do not believe the submitted changes are appropriate, you may be asked to make changes to your PR, or your PR may be rejected. If you do not make requested changes, the reviewers may edit or reject the PR. We reserve the right to reject a PR for any reason, not just for a reason explicitly enumerated in this document.

Style Guide

  • First and foremost, when editing, keep it similar to what's already in that document.

    • Do not arbitrarily change an existing style choice (like - vs * for bulleted lists, or _..._ vs *...* for italics) without a good technical reason.
    • If you are fixing an actual Markdown error that causes the final user manual documentation to render incorrectly, that is allowed (and encouraged).
    • Many sections of the User Manual were written before this Style Guide, and the style chosen by the original author of that section has been "grandfathered in". If you are changing something else in a small section of such a document, you can also update the style in that small section, but you should not make huge changes to the formatting without getting the agreement of the owner and/or maintainer(s) of the User Manual.

  • When referencing a menu item, like File > Open, make it bold, and use > as the separator-character between different levels.

  • When referencing a setting in a dialog box, make it bold.

    • Examples:
      • On the Settings > Preferences > Backup page, please enable ☑ Remember Current Session For Next Launch"
      • Use the checkbox Search > Find > Search Mode: ☑ Regular Expression to enable regular expressions in your search
    • The symbols ☐ and ☑ are used both for checkboxes and for radio buttons (because there aren't Unicode characters that are widely supported across fonts that are a good representation of a radio button)
    • Historically, some pages have used backtick monospace text for the options themselves, to disambiguate between the menu entry, dialog tab name, and dialog section header from the option. Please choose the new style, except when doing so will clash with the existing styling in a section.

  • For text that you want to indicate as user-entered (such as regular expressions or values entered into dialog box prompts), and for filenames and directories, use backticks to set the monospaced / code formatting.

  • Use the <kbd>...</kbd> tag around keyboard shortcuts (like Ctrl+F1), individual keypress (like Tab or Enter), mouse instructions (Ctrl+RightClick), and similar.

  • Special symbols may be entered by pasting in Unicode characters or using the appropriate &-entities. Please stick to common characters that are likely to be rendered on a variety of platforms with a variety of fonts.

  • Images should be used sparingly. If they are needed, keep the filesize small and place the image file in the content/docs/images/ directory.

  • Changes to the theme (whether it's just slight edits or a completely new theme, or anything in between) will not be accepted unless you have worked with the owner to make sure that the changes to the theme are necessary or appropriate.

Cross-Links

  • To link from one page in the user-manual docs to the top of another page, use the syntax [link name](../page/) . Note that in the link syntax, page does not include the .md extension.

  • To link to an anchor (like a heading) in another file, use [link name](../page/#anchor) ; or use [link name](#anchor) to link to an anchor (heading) in the same file. The anchor names are the lower-case version of the section headers, with spaces replaced by hyphens.

  • Example: from the Themes page, you can link to the Preferences > Style Configurator using the syntax [**Preferences > Style Configurator**](../preferences/#style-configurator).

Keep PRs independent

If you are making multiple PRs, please make sure you keep them separate. If you make a first change to change A to B and submit it as PR #N, then using the same branch (or a new branch that started from the first branch) and change C to D and submit as PR #M, then PR #M will contain the same changes as #N, in addition to the new changes. This will mean that if #N is rejected, #M will likely be rejected as well (because they contain the same changes that were rejected); and if #N is accepted (possibly with changes from the maintainers), then #M might come in conflict with #N; this also makes it harder to evaluate specifically what was intended for PR #M.

The best way to avoid this problem is to

  1. Fork from the main repository, or sync your existing fork with the main repository using GitHub's Fetch Upstream > Fetch and Merge feature
  2. Before making any new changes, create a branch specific to the one issue you are trying to fix
  3. Make those changes and submit a new PR from the branch back to the main repository
  4. If you want to make changes for another issue before the PR from step#3 was accepted and merged, create a new branch from your unmodified fork, so that it's starting from the same state that the main repository is currently in
  5. Make the changes in the new branch, and submit a PR from that branch to the main repository
  6. Now your PRs from #3 and #5 are independent, and #5 won't repeat or interfere with the changes from #3

If PRs are not kept independent, they may be rejected.