Composr Tutorial: Problem and feedback reports, and development policies

This tutorial will provide you some advice for reporting different kinds of feedback for Composr. It will teach you how to do it the right way, specifically:

• Comprehensively (you don't want to provide vague non-actionable feedback)
• Fairly (so that you're not expecting people to be working unpaid to meet your particular needs)
• Courteously (so as to not cheese anybody off)

It is written from the perspective of the core Composr developers.

Reporting bugs

We really want every tiny little issue in Composr reported. This includes everything from functionality being completely broken, to bad spacing of text or spelling problems.

Chris Graham, lead developer said

Everyone who finds problems in something free has a basic responsibility to report the problems, so that the project can advance, even if they are very small or you have already found a workaround. If you don't report problems, you have to assume that nobody else will, and hence the product will not advance.

This might mean making a bug report, or logging a feature suggestion – if something is not working as conceived, that's a bug, otherwise it's a feature suggestion. This section is about bug reports. Design/interface changes usually count as a feature suggestion, unless something is clearly not functional in the general case.

The Report Issue Wizard

The easiest way to report a bug or feature is to use our report issue wizard. The wizard will ask you questions specific to your selections so you are not overwhelmed by the Mantis bug tracker interface. The wizard will then create a tracker issue for you and provide you a link so you can upload files / screenshots or post comments on it.

What to expect

Don't expect a same-day response, after-all this is free software and developers are donating their time (when they can) to fix issues. But do post a reminder (e.g. a bug note / comment on the issue) if you get no response after a couple weeks. Sometimes a notification might not have gone through.

Bug fixes usually come with an automated (non-personal) response that includes a hotfix, a description of the bug, and/or a link to show the changes made in the code repository (git/github).

If you really do require an urgent priority response, then:

• You need to hire a professional to fix the bug(s) for you, and/or
• You should ensure you have a redundant backup policy so you can revert breaking changes until they get fixed

So please bear this in mind and structure your own processes accordingly.

Rules to follow

We don't want people to have to labour over bug reports. However there are some basic rules you will need to follow…

Before starting your report:

• Check the bug has not already been reported on the tracker. Don't spend more than 5 minutes looking, but at least have a glance over. You can also go to your Admin Zone dashboard. And in the version block, click the link which allows you to view issues reported for your version.
• Try not to report unrelated problems together. Generally speaking it is better each issue is reported separately so that it can be handled in one go without interdependence.
• Check it is a Composr bug. If it relates to a third-party addon (a non-bundled addon which is not offered on the downloads section of Composr), it should not be reported as a Composr bug.
• Check the FAQ. If your problem looks like it might be caused by a server configuration issue (for example if you are getting an 'Internal server error' message), please check our FAQ first.

What to include on your report:

• Use concise and specific language in the title / subject. The title / subject is what shows up on change logs for new releases of Composr. It's also what shows up when viewing issues as a list on the tracker. So simply saying "Issue with the downloads page" will confuse anyone who reads the change log, or developers who want to quickly know what each issue is about. Instead, be specific, such as "Opening the downloads page triggers a critical error: undefined function points_balance". Keep this short and specific; no more than a sentence.
• Describe your problem. If the problem it is at all complex it may also help if you can give precise steps to reproduce the problem. That said, we are a huge fan of TechSmith Capture, and often simply spending a few minutes recording a video means you won't need to type much explanation and your problem will be more easily understood without ambiguity or language problems.
• If you think there is any chance that the problem only happens on some browsers (e.g. some kind of layout problem or JavaScript problem), report which browser you are using in the Additional Information section (e.g. Mozilla Firefox 58). Generally you can find this in your browser's settings / about section.
• State which Composr version you are running. You are usually prompted for this in Mantis as 'Product Version'. The wizard also asks you for this. It helps us immensely to know what version you are running. And it categorises your issue so others running the same version can easily find it.
• If you get an error message, copy and paste the error message. The developers need to know precisely what it said, without paraphrasing or typos.
• If you see a stack trace, or are invited to generate one, include that full stack trace. Often stack traces are extremely useful. You should scan over the stack trace first though to make sure there isn't anything in there you wouldn't be happy sharing (such as your website URL, full file paths, or potentially passwords or sensitive text). If you find anything you do not want to share, simply censor it out of the report. Or, you can post your stack trace on the issue separately as a 'private' comment. Don't expect the developers to censor things for you; they don't have the time for that.
• Mention anything else that you might think potentially relevant to the situation. For example, if you have disabled JavaScript, made relevant changes to Composr settings, or are browsing on a phone, or have installed hotfixes in related areas of the code, or if you're on a really new version of PHP. We can't list everything that might be relevant here, and that's the point (don't consider the aforementioned examples a checklist): if something that is likely to be relevant comes to mind, include it.
• If your problem might be hard to reproduce, take some time to reproduce or to enable remote access for the developers, or be specific to your own server (e.g. only occur on certain PHP versions). If you wish to grant developer access then make sure you agree to the server access policy (designed to protect the developers from claims against them), and clearly include in your report that you agree and that you are happy for direct site access. The developers like to resolve bugs efficiently with the minimal amount of discussion, so if you can provide access immediately at the point of making your report it may help a lot (otherwise the developers may need to come back with questions, and the back-and-forth and second guessing could take a while). If you don't want to give live access you could consider cloning your site and providing access to the clone.

In general:

• Use a high-standard of English. Don't use l33t-speak, txtspk, or anything like Hinglish. If you don't write English well then try checking what you have written by passing it through a translator (e.g. Google Translate or Bing Translator). There have been many situations where users type English as they hear it in relation to their own language, not how it is spelt. This tends to force the developers to stare at their screens for 10 minutes to decode it.
• Use correct terminology. It's really important that you don't use substitute words when describing things - use the standard Composr and industry terms to prevent potential confusion. For example, if you said "I linked a download into my thread" then a strict interpretation of that would be that you added a Composr download through the CMS zone, and then put a link to it in a topic that was being viewed in threaded mode. However if you were misusing terminology you might simply have meant to say "I added an attachment to the first post in my forum topic".
• Don't be too vague or ambiguous. This is one of the biggest problems the developers have with reports, so think carefully and double-check what you've said. For example, you might not realise that saying "a button does not do anything" can be really hard to understand because it could mean lots of things such as:
  • Clicking the button in the browser results in absolutely no action at all on any level.
  • Clicking the button in the browser results in the button showing as clicked, but then the browser does not proceed any further.
  • Clicking the button results in something seemingly happening, except the browser just stays in a "loading" state without actually showing any result.
  • Clicking the button takes you to a white-screen.
  • Clicking the button takes the browser away and right back to where you were with no message.
  • Clicking the button triggers a JavaScript error.
• Don't write a long meandering essay. If you could convey as much meaning using fewer words, try and do that. Remember that the developers might have to read another 10 reports in the same morning, actually deal with them, and finish it all without having expended the energy required for their primary job. They don't have time to read too much narrative.
• Don't address someone in specific. Not every developer is available at all times. Whichever developer can resolve the issue will resolve the issue (assuming a developer can, which is not a guarantee for free software / support). Therefore, it is inaccurate to assume a specific person will resolve it.
• Write for a broad audience. Other users are probably also reading your report. Don't write the report as something about you and your site, try to keep the focus on the problem itself, and Composr.
• Assume the developers have amnesia. You may have previously interacted with the developers, and therefore assume details of this will be remembered. However, assuming 4 issues are dealt with per day, that means 1460 issues per year - so please forgive that the developers will often dump their memory after dealing with something. And remember that you may have a different developer interacting with you each time, or even within the same issue.

If you can't remember a PHP or Composr-critical error message, you may be able to find it in your error log (located in Admin Zone > Audit > Low-level logging). The error log shows all non-user-errors that have occurred on your site. If you cannot find the error on the UI (which truncates to the newest ones to prevent PHP memory issues), you can open your log at data_custom/errorlog.php.

If your report is not clear enough for the developers to immediately see it as a bug it may not be treated as such – so please make your reports as clear as possible.

Automatic reporting (telemetry)

Composr comes with an automatic bug reporting mechanism which may be disabled during installation and at any time in the site configuration. We prefer that users leave this option enabled, as it allows us to fix bugs that do not get reported. When enabled, some errors are sent to the homesite securely by encrypting it with a public key which was distributed with your version. Your error log (Admin Zone > Audit > Low-level logging) will indicate which errors were relayed. You can click a link for a relayed error to see if the developers added any status or information to it (e.g. maybe it was already resolved and a tracker issue will be provided for a hotfix). Sometimes a message is applied automatically / instantly (e.g. a reported error was already fixed) so developers don't have to sift through errors that were already fixed.

This automatic reporting mechanism should not be considered a substitute for reporting issues on the tracker. You should still report issues / errors to the tracker so that other members and developers can see it and discuss it.

Where to post

The "correct" place is the tracker or through our report issue wizard.

You could informally post an issue on the forum. But the developers don't promise to check the forum. The issue tracker is the best way for developers to keep issues organised. So it is highly recommended you post there.

Reporting security problems

You must report security holes or suspected security holes privately by marking the tracker issue as 'Private' (if reporting through the wizard, it will do this automatically if you chose security hole as the issue type).

Disclosing security holes publicly is very irresponsible because malicious users can spot those and exploit people's Composr sites before a patch is made. The core developer team will disclose the security hole after it has been patched.

This is a very serious offense, so you may be issued a warning / punitive actions for failing to report a security hole privately.

Reporting performance problems

On shared hosting it is always possible that a webhost can come along and say you are using too much resource.

Shared hosts fit many sites onto the same server, and depending on the price and reputability of the webhost, you may be allowed to use more or less server resource.

Webhosts may work on various metrics, or may respond to issues they have manually identified.

Database size

This could be an issue if you store a very large amount of data/content on your website. It has rarely, if ever, been reported as an issue for a Composr site. Composr has many cleanup tools and health checks in place to help remove old and unnecessary data from the database (and to alert webmasters when culprit tables get too large).

That being said, the biggest culprit table seems to be stats. If your stats table is very large (it is not uncommon for it to be multiple GBs on an active site), consider changing your Composr settings to store stats for a fewer number of days. This will not affect your stats graphs / pages so long as your system scheduler is working (the data for the graphs is stored separately).

Bandwidth

This could be an issue if you are hosting large files, such as videos or downloads, and a lot of people are downloading them. Composr itself has no particular high bandwidth requirement. But there is a setting you can set which allows you to limit the amount of bandwidth used in a given month (under Admin Zone > Setup > Configuration > Site options > Closed site).

Request volume

It may be that you have very large numbers of visitors. If you have many hits each second, the webhost may struggle to serve these requests. This is not specific to Composr. But you may consider using a load balancer on your server, or at the very least enabling Composr's rate limiting features in config_editor.php.

CPU usage

On a reasonably decent server, average Composr requests should be well under 1 second execution time on the server. 0.1 seconds is about right for a simple page on a well-configured server that isn't overloaded.

(Note that when we look at execution time, we're not talking about time between clicking and seeing a page – that is:
browser reaction time + latency + queue time + execution time + latency + render time + probably some other stuff)

So Composr doesn't use a lot of CPU inherently. However, CPU is probably the biggest limiting factor on a server. If you have 10 reqs/sec (requests per second), with each request averaging 0.5 seconds, then this would use 5 CPU cores constantly. For a normal Composr site that is a lot of visitors to get, but the webhost has to think of the server as a whole…

Let's imagine the webhost has 500 accounts on the server, and 7% of those sites receive a significant ongoing volume of hits to some kind of CMS (Composr, or others), averaging 1 per 10 seconds, each request taking 0.5 seconds to execute…
500*0.07*0.5/10=1.75 seconds of request per second of real time, probably enough to tax a dual-core server.
So you can see, depending on what kinds of customers the host has, what software they run, how many accounts are held on the server, and the power of the server, hosts may have to do some push back against what their customers might do.

If you are using the Composr chatroom, and a few people leave it open, the reqs/sec could rise considerably. The reqs/sec could also rise considerably if you use site-wide IM or if you use notification polling.

If you are going to run a popular CMS site, you will eventually outgrow shared hosting and need a VPS, dedicated server, or cloud instances. Until then, try and see past webhost marketing and choose a host that has a good reputation and good hardware – absolutely don't cheap-out and try and get really cheap hosting, as you'll suffer from it. Cheap hosting is ideal only for simple static sites that get few hits. It's really important to realise how cut-throat and difficult it is for webhosts – think how much salary a host needs to pay for the support you use from them, for the hardware they provide, for the marketing/advertising/offers they run, and for maintaining their business (their own website, etc) – you'll see how squeezed it is and how if you go on the cheap end you can't possibly do well from it.

Disk I/O

As of this writing, no Composr user has ever reported that a webhost has reported excessive disk I/O (input/output) to them, but it may be an issue affecting the performance of your site due to factors outside the scope of Composr. I/O can be a real performance bottleneck if the server is not well-configured, such as having a remote disk, a slow disk, a failing disk, or if other users on the server are doing something that is really making the disk 'thrash'. Composr won't thrash the disk, but it would be affected by another user doing so. Composr therefore does have some special options for limiting its need to regularly check the hard disk, discussed in the Optimising performance tutorial.

Memory usage

Normally Composr requests are explicitly limited to a maximum of 128MB, which is very small compared to the amount of RAM a server has (4GB is fairly typical nowadays). There are a very small number of one-off admin tasks where Composr raises or removes the limit, but its very unlikely to be a problem.

If a webhost complains about memory usage they are probably looking at an aggregate figure. If you get an error about PHP running out of memory, and you believe it is not because of tight PHP memory limits on your webhost but rather Composr using far more than it should, you can report it to the tracker.

Example: chatroom

The chatroom is one possible cause for an aggregate figure to rise, as it has regular hits for each person who has the chatroom open. This is because the chatroom has to be constantly checked for new messages (hopefully one day this won't be the case, but current PHP and web browser features prevent a smarter approach on shared hosting).

Let's say that 8MB is used by the chat message check script. This memory use is from the actual parsed PHP code that is loaded up, as PHP tends to use quite a lot of memory for it (orders of magnitude more than the disk size of PHP files).

The chatroom checks messages by default each 10 seconds (so on average a message will be received 5 seconds after sent).

If each request takes 0.05 seconds, and there are 20 people in the room…

20*0.05/10=0.1 seconds of request per second of real time

Assuming only a single server core, this means a server would be using the 8MB 10% of the time.

If the server has 1GB of RAM dedicated to web requests, it could sustain 500 customers using this volume of RAM.

So, the chatroom is unlikely to be a problem unless the webhost is really cheaping out in a big way (e.g. putting thousands of users on a subleased VPS).

Example: general use

If you have 50 users browsing the site, making a click every 10 seconds, and each hit is using an average of 23MB of RAM and taking 0.5 seconds to execute…

50/10*0.5=2.5 seconds of request per second of real time
2.5*23=57.5MB ongoing average RAM usage

(we're assuming the RAM is used flatly across requests, which isn't true, but all these calculations are approximations)

If there are 500 sites on the server and 7% are using this level of resource and the other sites aren't using notable resources…

500*0.07*57.5=2012.5MB RAM required on the server

As with the last example, it should not be a problem – but if the host has a lot of users on the same server, or users are using a lot of resources (maybe there's a trend to move to CMSs universally, and also spiders are heavily hitting all the sites regularly) it could be a problem.

If a webhost is complaining

If a webhost says you are using too many resources, find out specifics from them. Ask what URLs are causing problems, what resources are being used, and what is valid on their AUP (Acceptable Use Policy).

If the host has reasonable limits, and you aren't serving a high ongoing or peaking volume or users, pass on those specifics to the developers in a bug report.

If the host has unreasonable limits, change webhosts and give them a poor review.

If you are using too many resources for shared hosting, you'll need something better.

Reporting spam problems

» See advice provided in the Anti-spam settings tutorial. Note that if there is an issue with the anti-spam system itself, please report it to the tracker, but don't report general spam incidences on your site.

Requesting support

Generally, users can help each other out on the community forum.

Please don't demand free professional/official support. Members will provide the support they can provide when and if they can provide it. If you need guaranteed / urgent support or have a mission-critical architecture, consider hiring a professional instead.

Reporting and avoiding emergency problems

This section describes how to report emergency problems.

It is about:

• emergency events that have substantially and suddenly taken down your website
• …legitimate bugs or undocumented major usability problems that could seriously trip regular users up

It is not about:

• general bugs in functionality
• problems with your hosting, e.g. databases suddenly corrupting

If you have a major problem that you believe to have been caused by a Composr bug, you can open open a tracker issue for it.

It is important that you help the developers help you. Remember that the developers are not employed (they are members who volunteer their time to further the Composr project), so they have to fit it in within their availability. It is secondary to what pays their bills. You need to make it really easy for them to jump in to fix the problem. The developers will not want to:

• negotiate for the access needed to fix the problem
• have a protracted back-and-forth over hours or days
• have to schedule processing of the issue
• have to keep requesting additional information

Don't make the developers have to do detective work just to receive extra crucial information from you. Explain the exact situation and anything pertinent. For example, if it is a problem upgrading, describe the exact process you used to upgrade, what you upgraded from, and what you upgraded to.

In return, the developers will try their best to ensure unintended glitches don't cause you unnecessary pain.

Specifically for upgrading, you are advised to take backups as part of the upgrade process. The best process you could follow would be:

1. Take a backup
2. Do an upgrade
3. (Find it went wrong)
4. Move the current, broken site into a temporary directory (e.g. failed_upgrade), and rename the database (e.g. failed_upgrade)
5. Restore the backup to its original directory and database
6. Report an issue explaining the problem, and providing access to the temporary (failed_upgrade) site via the FTP fields on your member profile
7. (The developers would then do what is needed to investigate and solve the problem)

Bear in mind that the primary defence to something suddenly going wrong with your site is to take backups, and know how to restore them (having practised it at least once). The developers are committed to ensuring Composr's stability as a product, but bug fixing is not a free concierge service that puts the responsibility for your site onto the developer's shoulders. That kind of responsibility requires employing and/or contracting a developer and paying them for their time.

» Also see the Disaster recovery tutorial.

JavaScript problems

If you are finding background requests for pages are not getting called (AJAX), or in some cases frames (e.g. overlays), it may be a JavaScript problem. Additionally you could be getting explicit JavaScript errors popping up, or generally interactive in-page features might not work.

To report such issues it is best to take a screenshot of your JavaScript console. All modern browsers have this as a part of the developer tools, and it basically shows a log of all JavaScript errors that have happened since the page loaded.

Here are some tutorials on how to do that:

Cross-domain problems

Issues with AJAX and frames specifically can be caused by JavaScript security relating to access across domains. If JavaScript is asked to call one domain, from a different one, it might not allow it, to preserve the general security of the web.

In Composr it can happen if the base URL has changed. One possibility is if it is blank in the _config.php file. If it was never set, and sometimes Composr is getting called by different variants of the base URL (typically with and without 'www.') then the cache can get a mixture, and it triggers such cross-domain errors.

Providing feedback, or making feature suggestions

Feedback is one of the most important signals for us when developing Composr. Composr users are often able to show us ideas from new angles, which play a big role in Composr's future.

Most of the guidance for reporting bugs also counts for posting feature suggestions, so please review the advice above ("Rules to follow").

Additionally:

• Make sure your posting is reasonably comprehensive and self-contained. For example, if you are suggesting integrating with an external system then don't ask developers to go and do further research just to see what you mean – explain exactly what you want integrating, how, and why. Doing research can take hours, so if you ask for it you'll instead likely just find that the issue gets closed (remember, Composr developers don't get paid; if you want a developer to do the research, then pay them for it).
• Esoteric feature suggestions really aren't likely to be taken seriously, as Composr must not be allowed to become bloatware. Additionally big complex features/integrations need volunteers or funding, and when we see big esoteric requests like this it looks like a request for free work. Because otherwise such an esoteric thing wouldn't be brought to the tracker, they'd just be handled as some separate personal or commercial project. So such requests are not likely to receive a good response. Bottom line, if you make a feature suggestion, ensure that you believe multiple people will use it and benefit from it.

Unfortunately, it is often not possible for the developers to comment on whether or not any certain feature will be developed. In fact, this practice is discouraged since the development of features largely depends on developer availability (which may also depend on whether someone can pay them to develop it, if they are not willing to do it for free). There are too many variables in the Composr project to allow for a sort-of "road map" of feature development. Further explanations are detailed below.

Regardless, we have the feature tracker available for full discussions, so your feedback will always be heard by someone in the community, even if someone is not able to address it. In the spirit of Open Source you can even see ideas direct from the core developers. Features can be directly sponsored from the tracker (using points; if you want to financially sponsor an issue, see TODO).

If a developer declares 'yes' to a suggestion immediately

• They may need to find funding for development, as professional developers have to spend large amounts of time adding functionality. So, regardless of any developer's views, it often comes down to whether Composr users are able to sponsor functionality, hire someone to develop the feature, or develop it themselves.
• The community's plans for Composr might change for a good reason that they hadn't foreseen – meaning it wouldn't be included after all. This can happen if the design process reveals a big problem with the idea. This is often the case, even for core developers' own ideas. It would be a big problem if any of Composr users built their plans around a premature announcement.
• Even if someone develops the feature it might take longer than people were expecting, and this not only rushes them into making releases too early, but Composr users can develop a dependency that is unhealthy for not just the development process, but the health of the user's business/organisation.

If a developer declares 'no' to a suggestion immediately

The problem with this is that it almost always causes arguments – which of course we all wish to avoid.

The reason that arguments are so counter productive lies in the fact that development teams are never in a position where they can accept every suggestion from every user. They have to make wide and complex decisions, based on information most people never see, and based on decades of combined engineering and design experience. This can be far more complex than most people realise.

As a developer's perspective can be hard to explain, the harder they try and explain things, especially when rushed, the more likely the conversation will be perceived as belligerent, or at least very time consuming and distracting.

Read on to get a better idea of our perspective.

Why a developer might think 'no'

There are many reasons, but here are a few:

1. They may feel a feature over-complicates things;
2. They may feel a feature biases Composr in a particular direction;
3. They may feel a feature would cause performance problems;
4. They may feel a feature would introduce security risks;
5. They may feel a feature directly conflicts with other plans;
6. They may feel a feature would make Composr bloatware;
7. They may feel a feature breaks important engineering principles such as separation of concerns;
8. They may feel a feature is somehow incoherent with Composr's under-the-hood architecture, so would need many subtle and complex changes to numerous interconnected subsystems, and introduce risks of new bugs or confusion about redefined Composr concepts;
9. A feature could require skills or experience that no currently-available developer has;
10. For features relating to 'flexibility', developers sometimes feel that implementing yet another complex extra layer of control may be more complex to control than customisation of the actual PHP code (which Composr supports in a neat and controlled way);
11. Often members of software communities will travel down a rabbit-hole of feature suggestions as a poor substitute to having a proper budget for skilled and experienced developers working on a project. We are clear that non-trivial projects will always require some amount of designer and developer time, and no amount of loading Composr with features can change this, so at a certain point of complexity and specificity the advice would always just be 'hire a developer to code this directly'.

As well as 'yes' vs 'no', there are the matters of strategy and of release management, which are not simple.

Strategy

(Click to enlarge)

Each major Composr release usually hosts a wide range of new features, but also concentrates development on one particular overall objective. Typically the developers do this because they want to do something big and the only way to do it is to make a 'release mission'.

Considerations for a feature include:

• whether it matches the overarching mission
• perceived importance overall
• complexity / needed skills
• scheduling

This said, things don't always get planned smoothly:

• Feature sponsorships or developer contributions may take precedence over planned strategy
• Plans often change due to unforeseen changes in the web landscape
• Users making the developers aware of a major problem they were not previously aware of
• 'Eureka' features that are so good it's worth changing plans to include

Risk management

In patch releases the developers typically only fix bugs. However on some occasion they do fix oversights which they consider to:

• be at least moderately annoying
• be easy to fix
• introduce low risk of future bugs
• not introduce incompatibilities

Most features introduce risk in a number of areas, and all features are subject to some kind of prioritisation. For example:

• there is quite a large risk if the database structure is changed, due to complexities of upgrading.
• there is large incompatibility if the CSS is added to, because it means people's customised themes get busted.
• the feature changes a lot of code, or more significantly the APIs, breaking customisations or non-bundled addons.

 
 
It is best that risk and incompatibility is managed in bulk, in major releases. Sometimes the developers will compromise by introducing a small number of features in a minor release, which can be thought of as an in-between of a patch and a major release.

Rules of thumb

No free guarantees – There is no guarantee that someone will implement what you want. Open Source is not a free lunch, and volunteer Open Source developers makers only tend to implement things that are useful to themselves or fun to do. While Open Source programmers are usually highly ethical, and care about moving the world forward through cooperation, it's important to remember the best web developers are highly skilled and experienced professionals, like solicitors or doctors, and thus are paid as such. There's a lot of expertise in a lot of disciplines that is required to be a good web developer. At the very least, developers have bills to pay.

You can sponsor functionality – If you have some financial resources available then you can simply sponsor development financially to push things the way you want them to go. You can hire a developer to develop / resolve something on the tracker for you, or even provide ongoing maintenance of your site. If you don't have finances but you have points then you can sponsor an issue on the tracker using points. While this has far less power than financial compensation, at least the developer who implements the issue will receive the points (which boosts their voting power / ranks in the community and allows them to sponsor issues they want to see themselves).

Lead by example – Of course only a proportion of Composr users can afford to sponsor functionality. So, why not set an example for end-users making contributions by releasing something yourself (addons, themes, translations, pull requests, etc) – remember that if you don't release anything, you forfeit a right to complain if others aren't doing the same too. Demonstrating commitment to contributing to the product ecosystem (with deeds, not words) is much more likely to result in people being willing to help you out.

Contributing code

First, we all thank you for considering contributing to the future of Composr!

If you are releasing some code and would like it to be considered for official inclusion into future versions of Composr, you need to choose to assign dual copyright to yourself and to Christopher Graham. This gives the core team the option to include your work, without the possibility of any future legal problems. Potentially contributions could become critical to the software, and it'd be impractical to negotiate/remove each case of contributed code if required.

If you would like the project to consider including your code, mention when you post your work on the tracker (or make a pull request) that you're "assigning dual copyright with Christopher Graham" and be clear about what code it is that it applies to. Also, if you make a future version and do not want a past copyright assignment to carry forward, you should clearly state this too. If you want credit, please clearly request to have it included in the attributions part of the Composr licence. Be aware that assigning copyright is not something revocable, and it is not the same as just assigning us a licence, so please think carefully about what you want to do.

Providing design feedback

The Composr community occasionally sees feedback that the developers should improve the design of the default theme. Usually, however, this feedback is given in very vague terms and is hard to act on. This section will explain how to give design feedback in a clear constructive way, and also give some background on the design constraints that the developers work within to make Composr.

What not to do

Here's how not to give feedback:

Composr's design looks dated.

Composr doesn't look as good as Wordpress.

Composr doesn't look attractive.

The problem with this kind of feedback is that it very much reflects the perspective of the person giving the feedback, yet the details behind that perspective are entirely unknown to those reading the feedback and wanting to act on it. The person behind the feedback is sincere, but does not realise it doesn't help anyone move towards meeting their needs. There is a lot behind whether something looks "attractive" or "ugly", and it's very much about the fine details. In fact, someone looking at a design can feel it looks ugly without knowing why, and only on contemplation does it become clear that it is due to a small number of things in the details being slightly wrong. This is how the brain works, it makes lots of subconscious evaluations on your behalf.

It takes a great deal of self-control for analytical-minded developers to not see very vague negative feedback as something from a "style over substance" person who wants their whole website delivered on a plate for them. Fortunately, with just a little bit of work you can ensure that developers will not be under that false impression, that developers will be happy in their work, and give some actionable feedback that will have a positive effect on the future of Composr as a product.

Feedback types, in detail

In this section we'll analyse each of the above positions. Much of this will read as if it is a rebuttal, but that's not our true aim here. By explaining why things are as they are, and the process the developers work within, we can then explain how real design issues (which nobody would deny) can be fed back. It also gives you the insight required to challenge our processes or assumptions, should you feel the developers are doing things wrong.

Composr's design looks dated.

Often this largely is to do with how blocks look. A lot of modern designs will try and minimise the number of borders and separate shaded areas, and instead use white-space and more subtle dividing lines to lay stuff out. Composr may be thought of as "boxy".

Composr has a modular design because it is not a hard-coded system. Composr is constructed so that you may make many different kinds of website with it, and have full control of the layout. Therefore you construct a layout by putting together a number of components ("blocks" in Composr jargon). By default these blocks will look self-contained, because it's the best way the developers can make things work out of the box, without you needing to be an expert designer. Things are also quite close together by default because the developers need to support large numbers of features displaying at once, which is a very common configuration on community websites.

We provide a Comcode feature to "de-boxify" the appearance of blocks which helps a great deal. Designers can fully customise the appearance and the developers fully embrace the design process.

So, largely this feedback comes down to the fact that if you're creating a website you probably will want to do some amount of design to get things look great for your site. Design is a very human process. It's not truly a situation of Composr being dated, it's more of a situation that modern design quality really is driven by expert designers spending a lot of time and energy to perfect the design for individual websites. Because Composr is not a tool to clone out a standardised kind of website, great design cannot be fully automated.

Composr doesn't look as good as Wordpress.

The default Wordpress look is pretty dry and basic, so chances are this feedback more relates to comparing a Wordpress theme to the default Composr look. Or, considering the Composr Theme Wizard as comparable to installing a theme for Wordpress (it isn't – the Theme Wizard creates a colour scheme, which is pretty different). People do release themes for Composr; if the latest major release is quite new there may not be very many (or there may even just be the default theme), but you can try and encourage authors of older themes to upgrade them.

It is true that you may need to invest more in getting a Composr theme than a Wordpress theme, assuming you don't want a website as simple as a Wordpress website. This is because Composr solves more sophisticated requirements; themes are going to require more work because there is a lot more within a Composr website to design against.

Composr doesn't look attractive.

Usually this is more of an issue of a specific configuration of Composr looking a mess for some reason, or some kind of design mistake(s) in the default theme. In other words, it's not Composr as such, it is something specific – and thus, something the developers can resolve. This is where constructive criticism is useful.

How to give constructive criticism

This is best shown by example. The developers got some very vague feedback, mentioned in passing in our chatroom. It was not mentioned, but we were able to guess that this related to some display issues on the Composr demo, and analysis (read: second guessing) led to some bug reports, that the developers could then resolve:

• https://composr.app/tracker/view.php?id=1169
• https://composr.app/tracker/view.php?id=1170
• https://composr.app/tracker/view.php?id=1171
• https://composr.app/tracker/view.php?id=1172
• https://composr.app/tracker/view.php?id=1173
• https://composr.app/tracker/view.php?id=1175

This is exactly what the developers would like people to do directly. Isolate specific issues, then report them to us. We can then expedite the fixing of such issues very easily.

Beyond bug fixing

The spirit of the above section is much of one of treating design issues as bugs. That takes us a long way, but it is not the whole story. An overall design vision, and a sense of style/taste, is also a big part of the equation.

We need designers to get on board. You could actually redesign Composr interfaces yourself (e.g. in Photoshop) and submit them to the tracker for implementation by a developer as HTML/CSS (or make direct patches if you are so inclined). If you're a designer, you could certainly show non-designers how things could look a lot better.

Finding designers who truly understand how to design for CMSs, for user interfaces, for a wide range of considerations and constraints, and to truly be passionate about Composr as a system that serves non-designers, is difficult. Most designers design for specific contexts, which is in stark contrast to how software features are developed. 99 times out of 100, a regular professional designer is going to have far too much a limited perspective to truly take the Composr design up a notch.

So, if you're a designer reading this, there's a very good chance you could make an excellent contribution to the project because you know it better than most!

Further product design reflection

This section is not directly related to the process of reporting design issues, but may result in further insight into the Composr design process and help guide your feedback.

Fashion: there is a saying that "good design is timeless". This is largely true, but it is of course undeniable that:

• there are trends;
• the context we work within changes;
• the nature of how products behave or are used changes;
• improved technology allows better results.

The developers are unlikely to chase fashions with Composr, i.e. we will try and make the design as timeless as possible. To that end, the concept of it being 'dated' from a fashion point of view would likely be a null one. If your particular website is chasing fashion trends, you should invest in it, but Composr isn't likely to be redesigned only for trends, because the cost/disruption to do so would be very high compared to the benefit. Most really good designers understand that design is a lot more about solving problems, learning the best approaches, and optimisation, than it is at getting the latest look. However, what people think of as fashion trends, quite often are things we could treat more objectively, and therefore tackle within Composr's existing design framework without having to keep throwing everything out. For example, once curved borders were renderable by web browsers, the developers updated Composr to use them in many more places.

Modularity: This is discussed above, under "Feedback types, in detail"

Generality: Composr's default design has to be fairly conservative, suited for many different kinds of website. Design elements on a property retail website, may also be used on a community website, and a small business website.

Feature-density: Composr sites are often feature-filled. This means the default theme is unlikely to have much in common with very minimalistic designs, such as those on a portfolio website.

Backwards-compatibility: We have to avoid breaking people's themes too much across releases. We therefore have to choose compatibility break-points carefully.

Browser-compatibility: We have to make Composr work across a range of web browsers going back years, not just the latest Webkit/Blink.

Low-weight: Often designers working on custom websites will pick a lot of the very latest design frameworks and JavaScript libraries. However, with Composr the developers have to support a great number of features, without pulling in dependencies for them all. We can't have lots of different libraries with overlapping functionality, and different coding styles – Composr would suffer major performance problems, but also become a nightmare to design themes for. In recent years there has been an incredible churn in front-end libraries – what is hot one year, is outdated the next. It's very important that the developers isolate Composr from all this and try and make the default theme simple, consistent, and performant.

Opinion: It has to be noted that design is very personal, and not everyone is going to agree on what is good design. Different people have different taste.

Context: Something may look great in one context, but it may look messy in others. For example, a design element may look good with 10 words of text, but terrible with 1 word of text or with 30 words of text. A block may look great in a panel, but poorly spaced on a page, and not line up correctly in a page column. We will try and make things look good in all situations within Composr where we can, and make things adapt automatically, but it is just worth noting that people often don't realise that often nobody has seen things the way you are seeing them before, and this can be a very common cause for things looking bad. What you are doing on your own site will usually feel natural to you, but it's surprising just how many different kinds of visual configuration Composr can have and how much that can make a difference to how good things may look.

Pace of change: The state of the art in web design changes very quickly. Be aware that Composr will have release cycles, and that means we cannot always be on the cutting edge in the default theme.

Scope: Composr is a huge system, so not every interface will have received the highest level of design yet. This is a great area to give feedback in.

Conclusion

Things can always be improved.

Feedback. Tell us what looks wrong.
Feedback. Show us how you think things could look better.
Feedback. Be as specific, detailed, and clear as possible.

Feedback feedback feedback feedback.

General courtesy and guidelines

Don't start over-optimistic, then end up leaning on the core developers

Despite attempts to accurately describe what Composr can do, many people see Composr as a way of achieving the equivalent to what high-funded Silicon Valley companies achieve, but for free. Whenever there are roadblocks to that, people often end up trying to lean on the developers to get closer to it.

This can be very frustrating for the developers, who are probably as squeezed for time as anyone around. Building and maintaining Composr is a huge effort, and if individual users take more resources from the project than they provide through contributions/financially, it makes it unsustainable.

The developers are generally polite (if sometimes a bit curt due to time pressure), and they know a lot of people don't realise how much time responding to people can take, and the developers are empathic about people's technical challenges. But ultimately the developers can't save people from themselves and are often at the receiving end of people's frustration (with undue insults being relatively common).

So, please aim to:

1. properly plan out your project (written business plan, discussions and arrangements with investors if appropriate, SWOT analysis, written and costed specification);
2. think of Composr saving you a certain percent (say, 30%, compared to the effective budget of other successful live websites), not eliminating the need for a budget;
3. start reasonably simple (perhaps a minimum viable product, and agile development plan to iterate to/from that);
4. follow the advice given.

If you do then find it a big challenge to achieve your desired goals, don't approach the developers asking for free support or for new features to be implemented for free. Please do fully interact with other users in the community though, of course.

Avoid doing any of the following

1. Expecting core developers to work at specific times (they may be in a different timezone from you, they may only be on during certain times, or they may only work in their spare time)
2. Demanding free support, or calling the developers idiots for not doing your work for free, as "it'll bring in lots of paying customers"
3. When the developers say they can't (or won't) do something for free, twisting definitions (e.g. if something specific you want to do is not easy, call it a usability problem and call all usability problems bugs)
4. Not taking backups, then blaming bugs if anything happens to break your site, expecting free support to get it fixed
5. Sponsor a feature from a developer, then trying to use that to leverage free or discounted support in other areas (a sponsorship payment would go directly to fund the work involved implementing the feature, so would not be a donation)
6. Expecting people to work for less than they think they're worth
7. Pushing volunteers beyond their limits

Maintenance Policies

It is an unfortunate but inevitable fact that computer software has bugs. Composr is no exception, and although developers make a reasonable effort to fix as many bugs as they can, they aren't able to make sure everything always works (especially in past versions or in non-maintained / third-party features). It is essential that users understand the maintenance policy, and perform upgrades as suggested.

Bug policy

There are four classifications of bug:

• Security-hole. A security issue, such as someone being able to gain admin access when they should not have it.
• Major. A bug so severe that it breaks core functionality or entire sites (e.g. most pages throw a critical error), or it corrupts data.
• Minor. A bug that affects a small portion of some functionality (e.g. editing a download throws an error, but you can still view / add / download things).
• Trivial. A bug that does not break functionality (e.g. a spelling mistake, or field sorting doesn't work on a specific field on a specific table).

The developers don't usually immediately release a new version when there is a bug fix. They usually put out a hotfix (which can be applied either through the upgrader or by manually extracting the files), then a new patch release every couple of months. That is for supported versions: new releases of alpha and beta versions are put out on the needs of the development process rather than the needs of active users, so they are usually more frequent.

Composr works off a "rolling release" development process. New major/minor versions are released when ready, and then patch releases are made for the latest supported version only, not older versions (a rare exception might be if a massively critical bug or security issue is discovered in the previous version, but even then it is highly unlikely to be patched if the version is declared discontinued). It is up to webmasters to stay updated to the latest release, or apply fixes they need. There are a number of reasons for this policy, which is new as of Composr version 11:

1. We can focus our resources on the latest versions, rather than spreading ourselves thin.
2. Sites that are difficult to keep upgraded are usually 'forked' enough to need manual patching anyway – applying patch releases aren't an option for many sites, so why create them?

2b) We try to avoid that situation as much as possible in version 11 by using code overrides instead of making changes to original code (v11 has better support for it than v10; see item 4). That way highly-customised sites can still receive downstream fixes especially for security issues and major bugs.

1. As creating modern attractive web designs becomes more challenging, we expect users to rely on the improvements we create to the default theme more than they worry about maintaining their own customisations across upgrades.
2. We have made various smart ways of defining overrides in version 11, meaning it should be possible to define overrides that are less fragile across major/minor releases of Composr.
3. Eventually we (might) want to get to a point where upgrades are automatic, so that everyone can always be on the latest version – maintaining multiple versions gets in the way of this vision.

Please note that if Composr is installed by a hosting-control-panel, it is very unlikely that it will be up-to-date. Thus, hosting-control-panel installs will need immediate upgrade.

To see the current history of releases, see Maintenance status.

Security policy

Unfortunately it is virtually impossible to write computer code that doesn't have security issues, because even the smallest mistake or unintended-consequence can lead to them – the developers have very strong standards for writing code to minimise security holes, as well as in-house developed automatic scanning technology, and layers of redundant security built in to Composr itself. Even with all this though, problems will inevitably by found.

The developers believe in being open about how we treat security issues. By explaining how we deal with security issues and why we deal with them in the way we do, we hope that you can better understand how to manage incidents.

The developers have to address both the need to responsibly inform our users of the need to apply proper handling around security incidents, and the need to not make the lives of hackers easy by detailing vulnerabilities before a patch release can be distributed. Further, because Composr is an Open Source project, with a distributed community of developers, and clean public/immutable Git commit logs, we cannot hide vulnerabilities. We follow a security philosophy known as 'full disclosure', the basis of which is that vulnerabilities are specified in the open soon after they are found – but we do so responsibly.

Our policy is as follows:

1. Fixes for vulnerabilities will show up as soon as they are made in Git commit logs. These logs will show the presence of the vulnerability, and inevitably will provide hints to hackers on what a security hole might be.
2. The actual security reports will be kept permanently private on the tracker. Anyone posting a vulnerability should initially post it as private, but if not then developer(s) will make it as such as soon as they are aware and able. Anyone in the community with access to view the private issues will be expected to maintain confidentiality. By keeping the full details of a vulnerability temporarily private, it will in most circumstances make it more difficult for the typical hacker to learn how to exploit a vulnerability – giving the developers and users sufficient time to respond.
3. Within one month of the developers becoming aware of a vulnerability, they will put out a new patch release that deals with it, along with a full description of the vulnerability and any other important information (such as manual patches for those who do not wish to fully upgrade). The release notes for the new version(s) will mention that the upgrade addresses security issue(s). Wherever possible the time period will be much shorter than a month, measured in days.
4. The developers make no guarantee on posting information about the vulnerabilities on communication channels outside the main news section of the Composr homesite. This is to reduce the pressures on over-stretched developers for what will be a stressful period for them. It is the responsibility of Composr users to monitor this news and apply patches as appropriate. That said, the news section is automatically syndicated via Facebook, and available as RSS. It is also by default available on the Admin Zone dashboard of Composr sites. If other groups wish to syndicate security news more broadly, this is encouraged.

This policy applies to any code bundled with the main Composr distribution or held within the main Git repository.

The developers request any third-party security professionals implement their own responsible full disclosure policy, i.e. hold off before fully publishing details around a vulnerability.

The developers reserve the right to not disclose vulnerabilities that match any of the following low-risk circumstances:

1. Vulnerabilities the developers believe can not actually be exploited in practice due to additional layers of built-in defence (for example, CSRF vulnerabilities that security tokens mean can never actually be exploited).
2. Vulnerabilities that require staff privileges to begin with, and can only be exploited by some kind of associated social engineering attack. (As the staff could abuse their positions to undermine security by such social engineering attacks anyway, without any software vulnerability.)

These exceptions are carved out to ease burden on the developers and remove noise from the security announcement process.
This security policy may be amended based on particular unique contexts the developers find around vulnerabilities. The developers provide no guarantees or warranty: it is the responsibility of any Composr website owner to satisfy themselves with whatever level of additional support they may find is necessary for their organisation or business.

See also

• Choosing a software company for your project
• Minimum Viable Products
• Maintaining a good agency relationship
• Composr FAQ

Feedback

Have a suggestion? Report an issue on the tracker.