Contributing to gimme_readme

First off, thanks for taking the time to contribute! ❤️

All contributions are encouraged and valued. Please see the Table of Contents for different ways to contribute and read the relevant sections before making your contribution.

Following this guide will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉

If you like the project, but don't have time to contribute, no worries! There are other easy ways to support the project which we would also be very happy about. Please consider:

Starring the project

Tweeting about it

Referring this project in your project's readme

Mentioning the project at local meetups and tell your friends/colleagues

Code of Conduct

This project and everyone participating in it is governed by the gimme_readme Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to pwan6@myseneca.ca.

I Have a Question

If you want to ask a question, we assume that you have read the available Documentation and Examples.

Before asking a question, please search for existing Issues that might help you and like the comment of the original issue if you find something that matches your own. In case you have found a new distinct issue, please:

Open an Issue.
Provide as much context as you can about what you're running into. (Posting code snippets, screenshots, videos etc. are welcome!).
Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant.

We will then take care of the issue as soon as possible.

I Want To Contribute

Legal Notice

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Reporting Bugs

Before Submitting a Bug Report

A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.

Make sure that you are using the latest version.
Determine if your bug is really a bug and not an error on your side e.g., using incompatible environment components/versions (ensure that you have read the documentation. If you are looking for support, you might want to check this section).
To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the bug tracker.
Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue.
Collect information about the bug:
- Stack trace (Traceback)
- OS, Platform and Version (Windows, Linux, macOS, x86, ARM)
- Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant.
- Possibly your input and the output
- Can you reliably reproduce the issue? And can you also reproduce it with older versions?

How Do I Submit a Good Bug Report?

You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to pwan6@myseneca.ca.

We use GitHub issues to track bugs and errors. If you run into an issue with the project:

Open an Issue. (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
Explain the behavior you would expect and the actual behavior.
Please provide as much context as possible and describe the reproduction steps that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
Provide the information you collected in the previous section.

Once it's filed:

The project team will label the issue accordingly.
A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as needs-repro. Bugs with the needs-repro tag will not be addressed until they are reproduced.
If the team is able to reproduce the issue, it will be marked needs-fix, as well as possibly other tags (such as critical), and the issue will be left to be implemented by someone.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for gimme_readme, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.

Before Submitting an Enhancement

Ensure you are using the latest version of gimme_readme
Read the documentation and examples carefully to find out if a feature is already covered through an individual configuration.
Search the list of existing issues to see if an enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one and like the original issue's description.
Determine if your idea fits with the scope of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library.

How Do I Submit a Good Enhancement Suggestion?

Enhancement suggestions are tracked using GitHub issues, just like bugs.

To log a good issue, we suggest:

Adding a clear and descriptive title for the issue to identify the suggestion.
Providing a step-by-step description of the suggested enhancement with as many details as possible.
Describing the current behavior and explaining the behavior you expect to see instead, and why. You can also tell clarify which alternatives do not work for you.
Including code snippets, screenshots, videos, and/or animated GIFs to help demonstrate the steps of possible solutions or end results.
Explain why this enhancement would be useful to most gimme_readme users. You may also want to reference other projects that solved it better and which could serve as inspiration.

Your First Code Contribution

We're excited to help you make your first code contribution! Here's a comprehensive guide to get you started:

Prerequisite Tools

Node.js (LTS version recommended)
Git
Visual Studio Code - we have some recommended extensions to install

Development Setup

Fork this repository, and clone your forked repository to your local machine. Follow the guide here if you are unsure how to do this.

After cloning your forked repository to your local machine, navigate to the root of the cloned repository and run the following:

# Remove the pre-existing, global installation of the gimme_readme repository.
npm uninstall -g gimme_readme

# Install the necessary node_modules
npm i

# Simulate the environment as if gimme_readme was installed globally via `npm i -g gimme_readme`
# You can now use the `gr-ai` executable, and changes to your source code should be reflected when you make changes to the repo
# If your changes aren't reflected after changing the source code, repeat the commands above in sequence.
npm link

Making and Testing Changes

Create a new branch for your feature/fix:
```
 # Create a new branch, that is based off of your local main branch
 git checkout -b <branch-name> main
```
We maintain that it's always a best practice to never work off of your main branch, and instead, work on a separate branch. You should do your best to ensure that your local main branch, and your downstream main branch on GitHub, is in-sync with the upstream main branch.
After adding new code or modifying existing code, please try to add a test case for these changes if applicable (read the Running Tests Manually Section for more details). Run the following commands to ensure your current changes are: formatted properly, have no code lint (i.e., potential for bugs), and don't break any new or existing test cases:
```
 # To spot any formatting issues and automatically fix them
 npm run format

 # To spot any code issues (performed after formatting)
 npm run lint

 # To see if any of the existing tests are broken/need to be updated based on your update
 npm run test
```
NOTE 1: with regards to linting, there may be an off chance that you want to ignore a certain suggestion. We maintain that we normally don't suggest doing this, in favour of avoiding code that requires a linting rule to be ignored altogether. However, if it is absolutely necessary for you to ignore a rule so that ESLint does not complain, please see this guide.

NOTE 2: All of these scripts are defined in package.json, under the "scripts" section.

When you're ready to make a commit, this repository has been configured to run a pre-commit hook which also runs the following automatically, just in case you haven't done so already:

 # Formats all JavaScript files in src/ and tests/ directories using Prettier
 # This will automatically fix formatting issues like indentation, spacing, and quotes
 npm run format

 # Runs ESLint on all JavaScript files in src/ and tests/ directories (run deliberately after formatting).
 # This checks for potential errors, bugs, and code style violations
 npm run lint

 # To see if any of the existing tests are broken/need to be updated based on your update
 npm run test

This pre-commit hook aims to ensure that your commit passes the continuous integration tests. If your code fails the lint or test commands, you'll notice that your commit will not go through. You'll need to address these issues first, and then redo your commit.

Running Tests Manually

Like many other JavaScript projects, gimme_readme uses Jest to test the current behaviour of our source code. Please read more about how to use Jest for testing over here.

NOTE: using Jest with ES6 modules (e.g., using import for ES6 vs. require for CommonJS) requires using an experimental Node feature, which is explained in-depth in this Stack Overflow Answer. This affects our different test scripts within package.json - all of them start with node --experimental-vm-modules node_modules/jest/bin/jest.js.

With regards to the gimme_readme repository, the code within the src folder is tested by the code within the tests folder. Often times, when you're trying to add a new test or check if you have broken an existing test, you will want to single out these tests as opposed to running all tests.

Below, are several ways of running the gimme_readme tests from the command-line:

# Example 1: Run ALL test files
npm run test

# Example 2: Run test files within a certain folder
npm run test tests/unit/ai/models/

# Example 3: Run a singular test file
npm run test tests/unit/ai/models/geminiModels.test.js

# Example 4: Run ALL test files and get a coverage report for all files
npm run test:coverage

# Example 5: Run test files within a certain folder and get a coverage report for the selected files
npm run test:coverage tests/unit/ai/models/

# Example 6: Run a singular test file and get a coverage report
npm run test:coverage tests/unit/file_functions/_gr.test.js

# Example 7: Automatically run ALL test files when the source code changes
npm run test:watch

# Example 8: Automatically run test files within a certain folder when the relevant source code changes
npm run test:watch tests/unit/ai/models/

# Example 9: Automatically run a singular

Visual Studio Code Editor Integration

As mentioned in Prerequisite tools, part of developing gimme_readme involves using Visual Studio Code as your editor. When you open the gimme_readme repository with Visual Studio Code, it should suggest that you install several extensions if they haven't been installed already. Visual Studio Code specific configurations can be found in the .vscode folder.

Here are some explanations of the file at the time of writing:

Required Extensions: (.vscode/extensions.json)

{
  "recommendations": [
    "esbenp.prettier-vscode", // Prettier formatter integration
    "dbaeumer.vscode-eslint", // ESLint integration
    "streetsidesoftware.code-spell-checker" // Spell checking
    "yzhang.markdown-all-in-one",         // Enhanced Markdown support (e.g., shortcuts to make text bold)
    "DavidAnson.vscode-markdownlint"      // Markdown linting
  ]
}

If you don't have these extensions installed, Visual Studio Code will alert you to install these extensions.

Workspace Settings: (.vscode/settings.json)

{
  "editor.insertSpaces": true, // Use spaces instead of tabs
  "editor.tabSize": 2, // 2 spaces per tab
  "editor.detectIndentation": false, // Don't auto-detect indentation
  "editor.defaultFormatter": "esbenp.prettier-vscode", // Use Prettier as default formatter
  "editor.formatOnSave": true, // Auto-format files when saving
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit" // Auto-fix linting issues on save
  },
  "files.eol": "\n", // Use Unix-style line endings
  "files.insertFinalNewline": true // Add newline at end of files
}

JavaScript specific code snippet (.vscode/javascript.code-snippets)

{
  "Insert Current File Path Comment": {
    "prefix": "rpath",
    "body": ["// ${RELATIVE_FILEPATH/[\\\\]/\\//g}"],
    "description": "Inserts a comment with the relative path of the current file"
  }
}

Type rpath and press Enter to insert the current file's path as a comment.

Having these configuration files ensures that:

Code is automatically formatted on save using Prettier
ESLint problems are highlighted as you type
Common coding errors are caught early
All developers use consistent editor settings
Spell checking helps catch typos in comments and strings
Markdown files are properly formatted and follow best practices

NOTE: If the automatic formatting or linting isn't working:

Make sure you've installed the recommended extensions
Try reloading VS Code
Verify that the file you're editing is included in the paths specified in your npm scripts

Improving The Documentation

Documentation is crucial for our project's success. Consider updating:

The main README.md
The _examples folder's README.md

The following types of changes are welcome:

adding missing documentation
clarifying existing documentation
fixing grammatical and/or spelling mistakes

Attribution

This guide is based on the contributing-gen. Make your own!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing to gimme_readme

Table of Contents

Code of Conduct

I Have a Question

I Want To Contribute

Legal Notice

Reporting Bugs

Before Submitting a Bug Report

How Do I Submit a Good Bug Report?

Suggesting Enhancements

Before Submitting an Enhancement

How Do I Submit a Good Enhancement Suggestion?

Your First Code Contribution

Prerequisite Tools

Development Setup

Making and Testing Changes

Running Tests Manually

Visual Studio Code Editor Integration

Improving The Documentation

Attribution

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to gimme_readme

Table of Contents

Code of Conduct

I Have a Question

I Want To Contribute

Legal Notice

Reporting Bugs

Before Submitting a Bug Report

How Do I Submit a Good Bug Report?

Suggesting Enhancements

Before Submitting an Enhancement

How Do I Submit a Good Enhancement Suggestion?

Your First Code Contribution

Prerequisite Tools

Development Setup

Making and Testing Changes

Running Tests Manually

Visual Studio Code Editor Integration

Improving The Documentation

Attribution