The Isso community welcomes your changes. We don’t bite and are happy for anyone who donates their time and effort to the project.
You are welcome report issues at the GitHub Issue tracker.
Here are a few general rules to keep in mind when reporting issues:
Disqus import fails – if
isso import /path/to/disqus.xmlfails, 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.jsand 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.
You may notice some “weird” newlines in translations – that’s the separator for pluralforms in the templating engine.
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.
You’ve chosen to make Isso better and that’s great! Please follow this checklist when contributing code:
Submitting a change
Write proper commit messages (see next paragraph)
If adding features: Add or amend tests to cover the changes
Run all test suites (see Development & Testing) and make sure they pass
If docs changes needed: Update the documentation accordingly.
If it’s a user-facing feature or an important bugfix, add
Add yourself to
CONTRIBUTORS.txt, if you like
How to write good commit messages¶
Mention the affected part in the title (e.g.
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/posativ/isso/pull/356 with a fix for the placeholder-replacement code in `isso.js` as reported in https://github.com/posativ/isso/issues/524
…while this is a bad commit:
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
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?
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?¶
Improvements of test coverage - really important for the project to move forward!
Look at open issues with label “needs-decision” and chime in with your well thought-out opinion
Nicer automated testing, via docker or GH actions, of most of the available setup options (fastcgi/proxy configs, docker, apachge/nginx, …)
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
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.