ephemetoot

A command line tool to delete your old toots: 🥳 ==> 🧼 ==> 😇

View on GitHub

Introduction

Thanks for using ephemetoot, and for considering contributing to it! Some of the best features have come from suggestions and code contributed by people like you.

As Mastodon now has similar functionality built in, ephemetoot is now in maintenance mode - no new features will be added, only security updates.

You can contribute in many ways - improving the documentation, reporting bugs, suggesting new features, helping test new code, or even writing some code yourself. Following these guidelines will make the process smoother and easier for you and for maintainers and other contributors. That means everyone is happier and improvements get made faster 💫

Expectations

Adhere to the Code of Conduct 🤗

All contributors must adhere to the Code of Conduct for this project. If you do not wish to follow this Code of Conduct, feel free to direct your energies towards a different project.

Do not log security problems as public issues

If you have identified a security flaw in ephemetoot, please email ephemetoot@hugh.run to discuss this confidentially.

Check existing issues 🧐

Your bug or enhancement might already be listed in the issues. It’s a good idea to check existing issues before you log your own. If you like someone else’s enhancement suggestion, please “upvote” it with a 👍 reaction. If you have also experienced the same bug as someone else, you can add any useful additional context to the existing issue.

Always log an issue 📝

If you would like to contribute code or documentation changes that do not already have an issue listed, you should always log an issue first. Please do not add pull requests without prior discussion. Whilst pull requests are very welcome and encouraged, if you don’t log an issue for discussion first, you may end up wasting your time if someone else is already working on the same feature, or maintainers decide it isn’t a good fit. This also allows for your proposed feature to be scoped before you get too deep in the weeds coding it.

Regardless of whether is is a bug report, feature request or code proposal, provide as much detail as possible in your issue, and give it a clear name.

One issue per bug or suggestion ☝️

Each issue should refer to a single bug or enhancement. Don’t include multiple suggestions, or a mix of bug report and enhancement proposal, in a single issue. Multiple items in the one issue ticket will make it confusing to know when to close an issue, and means that maintainers will probably have to create new issues so that each task can be tracked properly. It also makes it hard to maintain a clear discussion thread in the issue if there are multiple things being discussed.

Issue and commit naming conventions ✏️

Issues should have clear names that describe the problem or the proposed enhancement. Past examples of good issue titles are:

Commit and pull request messages should start with an imperative verb. Simple commits such as documentation fixes may only need a brief sentence. Something bigger like an enhancement should usually have a heading briefly describing the outcome of the commit, with a longer explanation underneath. Past examples of good commit titles are:

Pull requests should include tests (if you can) ⛳️

We aim to have as close to full test coverage as possible: if you know how to write tests, please include them with your Pull Requests. Tests are run with pytest, which has pretty good documentation, so if you’re new to pytest or new to testing, take a look at the docs. If you want to contribute a new fix or feature, but don’t know how to rwite a test, you can also request assistance from a maintainer.

Closing issues in pull requests 🏁

When your pull request resolves an issue, you can optionally use one of the magic words to automatically close the issue. An example of a longer commit messages that does this is Add --version flag. The pull request template includes wording for this so you just need to add the issue number.

Use ‘black’ code formatting standards 🖤

We use black to maintain code formatting consistency. Thanks to @MarkEEaton for the suggestion. You should generally run black . in the main ephemetoot directory before making a pull request, or alternatively check that your code is formatted to the black standards. Maintainer @hughrun often forgets to run black so logging an issue about code formatting is completely legitimate 😀

prefer configuration over flags ⚙️

When adding a new feature, you should probably use a new, optional value in the configuration file, rather than a new command line flag. As a general rule of thumb, use a flag when your change will affect the output, and a config value when it will affect the actions.

For example, we use a configuration file boolean value for keep_pinned because that affects the actions - if it is set to “true” then pinned toots are not deleted, and if set to “false”, pinned toots are deleted. On the other hand we use the --datestamp flag to print a datestamp against each action as it is logged. This doesn’t change the action, merely the output to the screen or log file.

There are some exceptions to this general rule (--test prevents any real actions, for example), but the exceptions should be rare and reasonably obvious.

Prefer top-level functions ⬆️

Putting functions inside other functions can make the codebase confusing to understand. Wherever possible, prefer to define standalone functions and then call them from wherever they need to be used. This keeps our code DRY and makes it easier to test.

Your first contribution

First time contributors are warmly encouraged! If you have never contributed to a project on GitHub or another public code repository, the ephemetoot maintainers can help you through the process.

Terminology 📙

You can contribute in many ways - even pointing out where the documentation is unclear will be a real help to future users. Already confused by some of the terms here? Check out First Timers Only for some tips.

Pull Requests 🤯

“Pull Requests” can be confusing. You can learn how the process works from this free series How to Contribute to an Open Source Project on GitHub.

This is a pretty small project so there usually won’t be a lot of issues waiting for someone to work on, but keep an eye out for anything tagged good first issue - these are especially for you!

Help

You can get in touch with Hugh at @hugh@ausglam.space if you need help contributing or want to discuss something about ephemetoot.