Contribute

I am looking to…

… report an issue

… translate Isso into my language

… improve the documentation

… contribute code

The Isso community welcomes your changes. We don’t bite and are happy for anyone who donates their time and effort to the project.

Report issues

You are welcome report issues at the GitHub Issue tracker.

If you need help or want to request a feature, please open a discussion instead. For more ways to get in contact, see the Community page.

Here are a few general rules to keep in mind when reporting issues:

  • Disqus import fails – if isso import /path/to/disqus.xml fails, please do NOT attach the raw dump file to GH:Issues. Please anonymize all IP addresses inside the <ipAddress> tag first, as second step, replace all <email> addresses with a generic one.

  • embed.min.js-related issues – if you get a cryptic JavaScript error in the console, embed embed.dev.js instead of embed.min.js and create an issue with ±10 lines of code around the error.

  • Isso-related issues – Copy and paste traceback into a ticket and provide some details of your usage.

Translations

Isso supports multiple languages and it is fairly easy to add new translations. You can use the english translation file and other translations as a referece and open a Pull Request.

You may notice some “weird” newlines in translations – that’s the separator for pluralforms in the templating engine.

Documentation

Documentation improvements are sorely needed. Anything that makes the experience for a newcomer more pleasant is always welcome. Please see the Writing Documentation page for more details.

Code contributions

You’ve chosen to make Isso better and that’s great! Please follow this checklist when contributing code:

Note

Submitting a change

  1. Write proper commit messages (see next paragraph)

  2. If adding features: Add or amend tests to cover the changes

  3. Run all test suites (see Development & Testing) and make sure they pass

  4. If docs changes needed: Update the documentation accordingly.

  5. If it’s a user-facing feature or an important bugfix, add CHANGES.rst entry

  6. Add yourself to CONTRIBUTORS.txt, if you like

How to write good commit messages

  • Mention the affected part in the title (e.g. setup.py)

  • Keep title under 50 characters if possible, at most 72

  • Keep body under 80 characters of width

  • Explain what the change does

  • Link to related issues or references

  • Ideally, how to verify that this commit does what it says

For example, this a good commit:

js: Postbox: Use labels rather than placeholders

Placeholders are is meant to be a hint (an example input)
for the user about what to enter into the field, but
shouldn't be used in lieu of a <label>.

See following links for further justification:
- https://www.tpgi.com/html5-accessibility-chops-the-placeholder-attribute/
- https://www.nngroup.com/articles/form-design-placeholders/
- https://www.maxability.co.in/2016/01/03/placeholder-attribute-and-why-it-is-not-accessible/

This commit is a reland of
https://github.com/isso-comments/isso/pull/356 with a fix for the
placeholder-replacement code in `isso.js` as reported in
https://github.com/isso-comments/isso/issues/524

…while this is a bad commit:

Fix classes

It does not tell the reviewer which part is affected, why it is necessary or why this particular way of doing things was chosen. The commento docs have a more extensive explanation of good commits.

Considerations when submitting changes

The following sections will help you decide how to tackle larger architectural issues and help avoid wasted efforts for changes that are unlikely to be accepted.

You do not have to read this whole section; the maintainers will give you feedback in the review process. But if you want to be a nice and helpful person, you can make the lives of the maintainers a lot easier. These guidelines are here to help your thought process and hopefully make you aware of a few aspects you might not have thought about yet.

Design philosophy / Zen of Isso

  • Isso should not be a “move fast and break things” project.

  • Be mindful of the users. They do not anxiously await a new release - they simply want their websites to work.

  • Try to avoid breaking changes: People do not want to dig through changelogs to find out why suddenly their comment section is gone.

What kind of changes will be accepted?

As a rule, you want to make the life of the maintainers as easy as possible. Removing cruft is good, as is improving tests or docs. Introducing new features, possibly with new config options, should have good reasoning and is harder to review.

What should I think about?

  • Will everyone benefit from my contribution or is this just fixing my pet peeve/supporting my exotic use case?

  • Will this add complexity? If many changes similar to mine are introduced, will this make the project more confusing and complex?

  • Should this be done in a more generalized manner? As a hypothetical example, do not create a new toggle with is-submit-button-green or submit-button-color, but rather create a mechanism by which the color of all buttons can be set.

If adding a new option/config:

  • Is the option well-named? Can users already figure out what it does, without having to read the description?

  • Is the option really necessary? Should the default behaviour be changed instead?

  • Is the option well-documented? Is it clear what it does? Are the available choices well-documented?

  • Is the option in the right config section?

  • Backward compatibility

A config option is sort of a promise to users. They will be confused if it is removed and their setup no longer works.

What is currently needed?

@posativ’s wishlist:

  • Admin Web Interface – administration via email is cumbersome with a high amount of comments. A administration web interface should include the ability to:

    • Delete or activate comments matching a filter (e.g. name, email, ip address)

    • Close threads and remove threads completely

Regarding fancy new CI tools

  • Linters are fine, but please create sensible configs

  • Nothing too “magic”, AI-based

  • Keep in mind that too many bots running will need constant updates and maintenance

  • Nothing that compromises this project’s integrity, by granting repo access to bots

  • Nothing too “chatty” - it will just be ignored and increase the burden on maintainers even more

Complexity

Isso started out as a fairly simple project, but it has grown over time. It is built using many different technologies and moving parts

Below is a non-exhaustive list of tools, services, dependencies and technologies Isso’s contributors and maintainers need to at least peripherally be aware of - that’s a lot to demand of someone! Your aim should be to reduce this complexity, not add to it.

  • Docs

    • apiDoc

    • sphinx with reST syntax

  • Python

    • Pallets project: werkzeug, jinja2, flask

    • misaka (and changing config opts)

    • bleach, html5lib

    • Different python versions, OS versions

    • setuptools, pip

    • Python Package Index (PyPI) uploading

  • Python testing

    • pytest (unit testing)

    • coverage

    • flake8

  • Convenience tools

    • Docker

    • Vagrant

    • Ansible

  • Javascript

    • Node.js

    • npm

    • package.json oddities

    • webpack

    • Jest

    • puppeteer

    • Browser compatibility and ES5/ES6 standards

  • Development tools

    • make

    • Github Actions

  • Deployment options

    • isso run [opts]

    • Apache (mod_wsgi)

    • Apache (mod_fastcgi)

    • Apache (proxy)

    • nginx (proxy)

    • uwswgi

    • gunicorn

    • gevent

  • Importers

    • Current disqus export format

    • Current and past Wordpress export formats