Contributing to mffer

Guidelines, notes, and tips for adding to the mffer project

Any questions, comments, or concerns can be posted in the GitHub repository’s issues list.

Introduction

Thank you for your interest in this project. Contributions of any kind are welcome, but most useful to the project are bug reports and possible fixes. Whether you find a problem that you can fix or not, however, you can send feedback; follow, fork, or star the project on GitHub; tell others about the project; or just use the programs yourself.

This document includes information ranging from appropriate behaviors when contributing to the project to general instructions for contributing. It does not include many technical details, such as the project design, coding styles, or recommended tools. For those, dive into the Development Guide. For other information about the mffer project, visit https://dev.mffer.org.

Quick Questions & Answers

  • Where should I report bugs, request new or changed features, or ask for more help?

    The GitHub issues page is just fine for all of these things. Your “issue” doesn’t have to be perfect—others can ask for more details as needed.

  • I don’t know how to program, so how can I help?

    Answer questions on the GitHub issues page, make edits to documentation, or just offer a kind word.

  • What format should I use for a pull request?

    The best format is “submitted”! Ask questions, expect feedback and changes, and please submit PRs even when you’re still working on them. For the nitty-gritty details of coding style, merge types, and so on, please refer to the development guide.

  • What’s a “pull request”?

    Ah, you’re new to git and its style of shared development. Welcome! I’m glad you’re here. There’s lots of information available to get you started. First Contributions is one place to learn the general process of the “fork-clone-edit-pull request” workflow. For plenty more details, try Getting Started with GitHub.

Behavioral Expectations

The abilities needed to effectively contribute to an open source project are complex, intertwined, and widely varying. None, however, is more important than the ability to work with others kindly. People are different. Respect and celebrate those differences. Failure to do so will result in being asked to cease interactions with the project and reporting your account to GitHub. Disrespectful comments will be edited or removed. Any concerns may be addressed to the project maintainer, chjones@aleph0.com.

While this is the guiding spirit of the contributions to the project, the project has formally adopted the Contributor Covenant 2.0. In addition, users and visitors are expected to follow the GitHub Community Guidelines and the GitHub Terms of Service. None of these documents is intended to allow or encourage behavior disallowed or discouraged by the others.

Let’s do better.

So you’ve got this idea…

Wonderful! Think about it a bit. Try to explicitly define (even if just mentally) what it is you’re trying to do and how. Then take a look at the GitHub issues page and search for ideas like yours—someone else may have already made progress, run into problems that need to be fixed first, or had a discussion about alternate methods that could be better. That’s great! Minds working together, even asynchronously, produce excellent results.

Post an issue yourself talking about your idea. Start discussing it openly; there’s not a great benefit in “saving up” until your idea is near completion (or you’re stuck). Even if you don’t know exactly how to do what you want, others may be able to point you in the right direction.

Take a look at the Development Guide, and figure out how your idea best fits into the project: should you edit some documentation, write a program that uses the mffer as a library, or write a better algorithm for reading from the filesystem? This may also lead you to browsing the source code or reviewing the API.

Fork the project, make the changes you want, ensure it works the way you think it should (and doesn’t break anything else) and submit a pull request to merge your new code with the main project. It’s okay if it’s not perfect or even finished; once you submit a PR the code can be reviewed by others and you can make more changes before the final version is added to main.

Finally, bask in the warmth that comes from making a contribution to your compatriots. Celebrate your inquisitiveness and industriousness. Enjoy your creation.

And maybe you have another idea…

Contact

Any questions, comments, or concerns can be posted in the GitHub repository’s issues list or emailed to the owner, chjones@aleph0.com.