So you've started using
mkdocs-newsletter and want to show your gratitude to the project,
depending on your programming skills there are different ways to do so.
I don't know how to program¶
There are several ways you can contribute:
- Open an issue if you encounter any bug or to let us know if you want a new feature to be implemented.
- Spread the word about the program.
- Review the documentation and try to improve it.
I know how to program in Python¶
If you have some python knowledge there are some additional ways to contribute. We've ordered the issues in milestones, check the issues in the smaller one, as it's where we'll be spending most of our efforts. Try the good first issues, as they are expected to be easier to get into the project.
We develop the program with TDD, so we expect any contribution to have it's associated tests. We also try to maintain an updated documentation of the project, so think if your contribution needs to update it.
We know that the expected code quality is above average. Therefore it might be changeling to get the initial grasp of the project structure, know how to make the tests, update the documentation or use all the project technology stack. but please don't let this fact discourage you from contributing:
- If you want to develop a new feature, explain how you'd like to do it in the related issue.
- If you don't know how to test your code, do the pull request without the tests and we'll try to do them for you.
Questions, feature requests and bug reports are all welcome as issues. To report a security vulnerability, please see our security policy instead.
To make it as simple as possible for us to help you, please include the output of the following call in your issue:
python -c "import mkdocs_newsletter.version; print(mkdocs_newsletter.version.version_info())"
or if you have
make installed, you can use
Please try to always include the above unless you're unable to install
mkdocs-newsletter or know it's not relevant to your question or
mkdocs-newsletter is released regularly so you should see your improvements release in a matter of days or weeks.
Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change before creating a pull request.
If you're looking for something to get your teeth into, check out the "help wanted" label on github.
To make contributing as easy and fast as possible, you'll want to run tests and linting locally.
make format to fix formatting,
make to run tests and linting &
to build the docs.
You'll need to have python 3.8 or greater, virtualenv, git, and make installed.
Clone your fork and go into the repository directory:
git clone firstname.lastname@example.org:<your username>/mkdocs-newsletter.git cd mkdocs-newsletter
Set up the virtualenv for running tests:
virtualenv -p `which python3.8` env source env/bin/activate
pdmour package manager with the next command or using any of the other recommended methods.
curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -
Install mkdocs-newsletter, dependencies and configure the pre-commits:
Checkout a new branch and make your changes:
git checkout -b my-new-feature-branch
Run tests and linting:
There are more sub-commands in Makefile like
securitywhich you might want to use, but generally
makeshould be all you need.
If you need to pass specific arguments to pytest use the
ARGSvariable, for example
make test ARGs='-k test_markdownlint_passes'.
Build documentation: If you have changed the documentation, make sure it builds the static site. Once built it will serve the documentation at
Commit, push, and create your pull request.
Make a new release: To generate the changelog of the new changes, build the package, upload to pypi and clean the build files use
We'd love you to contribute to mkdocs-newsletter!