Skip to content
This repository has been archived by the owner on Jun 18, 2022. It is now read-only.

Latest commit

 

History

History
163 lines (127 loc) · 8.26 KB

CONTRIBUTING.md

File metadata and controls

163 lines (127 loc) · 8.26 KB
Raw

Contributing to FreeMAN

Contributions are welcome and necessary. Thanks for taking the time to do so!

The following is taken and adapted with respect from Atom's Contributing Guidelines.

How to contribute

Reporting Bugs

This section guides you through submitting a bug report for FreeMAN. Following these guidelines helps us understand your issue and reproduce the behavior.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Submitting A Good Bug Report

Bugs are tracked as GitHub issues. Create an issue on that repository and provide the following information by filling in the template.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.

  • Describe the exact steps which reproduce the problem in as many details as possible. This is not to inconvenience your life, but to make it:

    1. Much easier to identify the issue in the first place and
    2. Verifiable that the issue has been fixed once work on it has been done

  • Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.

  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.

  • Explain which behavior you expected to see instead and why.

  • Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.

  • Include logs, which are created using electron-log and stored at {appData}/log.log (see here to find information about appData).

Please provide more context by answering these questions:

  • Did the problem start happening recently (e.g. after updating to a new version of FreeMAN) or was this always a problem?
  • If the problem started happening recently, can you reproduce the problem in an older version of FreeMAN? What's the most recent version in which the problem doesn't happen? You can download older versions of FreeMAN from the releases page.
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
  • If the problem is related to working with files (e.g. opening and editing files), does the problem happen for all files and projects or only some? Does the problem happen only when working with local or remote files (e.g. on network drives), or with large files? Is there anything else special about the files you are using?

Include details about your configuration and environment:

  • Which version of FreeMAN are you using? You can get the exact version by running freeman --version|-v in your terminal, or by starting FreeMAN and opening Help -> About.
  • What's the name and version of the OS you're using?
  • Are you using custom configuration files freeman.settings.json, freeman.keys.json, freeman.themes/*.json? If so, provide the contents of those files, preferably in a code block or with a link to a gist.
  • Which keyboard layout are you using? Are you using a US layout or some other layout?

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for FreeMAN, including completely new features and minor improvements to existing functionality. Following these guidelines helps us understand your suggestion.

Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

  • Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

Submitting A Good Enhancement Suggestion

Enhancement suggestions are tracked as GitHub issues. Create an issue and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs which help you demonstrate the steps or point out the part of FreeMAN which the suggestion is related to. You can use this tool to record GIFs on macOS and Windows, and this tool or this tool on Linux.
  • List some other file managers or applications where this enhancement exists.

Your First Code Contribution

Unsure where to begin contributing to FreeMAN? You can start by looking through any first timer friendly issues. That being said, other issues may be well worth the venture, and I'm receptive and supportive of any contributions and questions supporting those contributions.

Local development

FreeMAN can be developed locally. For instructions on how to do this, see the README.

Pull Requests

  • Fill in the required template
  • Do not include issue numbers in the PR title
  • Include screenshots and animated GIFs in your pull request whenever appropriate.
  • I'm not interested in flaky stylistic preferences for code. If it passes npm run lint and I don't like it, I may update linting rules after the PR.
  • Include thoughtfully-worded, well-structured Mocha tests in the test folder. Run them using npm run test.
  • Document new code based on the Documentation Styleguide
  • End all files with a newline
  • Avoid platform-dependent code
  • Place imports in the following ordered groups (npm run lint will order the groups themselves):
    • Modules from node_modules
    • Local Modules

Styleguides

Git Commit Messages

  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line
  • When only changing documentation, include [ci skip] in the commit title

Documentation Styleguide

  • Some manual checking is unfortunately still required, since @inheritDocs is poorly supported in tslint. All elements other than local variables (i.e., const, var and let variables) must be JSDoc documented
  • Avoid one-line comments in favour of clearer code (meaningful names, smaller methods, logical flow etc.)