Skip to content

Latest commit

 

History

History
110 lines (74 loc) · 6.84 KB

CONTRIBUTING.md

File metadata and controls

110 lines (74 loc) · 6.84 KB

Contributing to Argmap

Collapsible Section: Table of Contents

Hello!

As I write this, I tried out dsanson/argmap only 10 days ago and that was my first time using Lua. I made my first ever pull request 4 days later.

So I'm still very much learning how to do this, and I could use all the help I can get! :)

There are many ways to contribute, from writing tutorials, improving the documentation, submitting bug reports and feature requests, commenting on issues, or writing code which can be incorporated into Argmap itself.

Suggestions and Improvements

Anyone can submit an issue to Issues · s6mike/argmap or comment on an existing thread. Common reasons are to:

  • Suggest features.
  • Report bugs.
  • Request help with difficult use cases.
  • Ask questions.

Reporting bugs

Think you found a bug? Please check the list of open issues to see if your bug has already been reported. If it hasn't please submit a new issue.

Here are a few tips for writing great bug reports:

  • Only include one bug per issue. If you have discovered two bugs, please file two issues.
  • Describe the specific problem as clearly and concisely as possible. (e.g. do say "argmap2mup breaks with error X when I try and convert this file: Y", don't say "getting an error").
  • Include the steps to reproduce the bug, what you expected to happen, and what happened instead.
  • If you can, please install the latest GitHub version and its dependencies, and verify that the issue still persists.
  • Include what version of the project you're using, as well as any relevant dependencies: Use luarocks list > luarocks_list.txt to get a list of lua modules and versions.
  • Even if you don't know how to fix the bug, including a failing test may help others track it down.

How to suggest a feature or enhancement

If you find yourself wishing for a feature that doesn't exist in Argmap, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that Argmap has today have been added because our users saw the need.

Feature requests are welcome. Please take a moment to find out whether your idea fits with the scope and goals 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.

Please provide as much context as possible, including describing the problem you're trying to solve.

Open an issue which describes the feature you would like to see, why you want it, how it should work, etc.

How to Contribute Code

Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.

This repo uses Github Flow: all code changes happen through pull requests

Pull requests are the best way to propose changes to the codebase (we use Github Flow). We actively welcome your pull requests:

  1. Open an issue for the change if there isn't one already. If you are making visual changes, include a screenshot of what the affected element looks like before the change. And if possible a mockup of what is planned after.
  2. Fork and clone the project.
  3. Create a new branch: git checkout -b [my-branch-name]. Note that most of my fixes and improvements are currently on the bugfixes branch, while the changes on the master are much more conservative. So it's worth discussing in the issue which branch to base yours on.
  4. Make your change, add tests, and make sure the tests still pass.
  5. Push to your fork and submit a pull request.
  6. Pat your self on the back and wait for your pull request to be reviewed and merged.

Interesting in submitting your first Pull Request? It's easy! You can learn how from this free series Course - How to Contribute to an Open Source Project on GitHub from @kentcdodds on @eggheadio

Here are a few general guidelines for proposing changes:

  • Each pull request should implement one feature or bug fix. If you want to add or fix more than one thing, submit more than one pull request.
  • Please keep your coding style consistent with what's already there:
  • Do not commit changes to files that are irrelevant to your feature or bug fix.
  • If you are changing any user-facing functionality, please be sure to update the documentation.
  • Write a good commit message.

Running Tests

Some simple tests are executed here: test/test_scripts/tests.sh.

I have also set these up to be called from a pre-commit hook.

Additional Resources

This file was adapted from: minimal/CONTRIBUTING.md at master · pages-themes/minimal :)

Copyright 2022 Michael Hayes and the argmap contributors SPDX-License-Identifier: MIT