Bug reports & feature requests
The English Farm is a complex application with a lot of moving parts. Things break. To make fixing them easier and faster, it is important when you report a bug that you give us as much information as possible. Likewise, if you have an idea for an improvement, being precise about things helps a lot.
Please don't post bad bug reports. Bad bug reports or feature requests are vague and will require follow up questions to establish the nature, location and symptoms of the issue or motivations for the improvement.
A bad bug report just says something like, "The schedule is not working" or refers to "a student" or "a lesson". A bad bug report shows a cropped screenshot, and doesn't give all the information we need (like what do you expect to see or happen) or give valuable points of comparison.
Good bug reports and feature requests include the following:
- A summary that is short and to the point.
- A clear and concise description of the issue. Tell us the who, what, when, where and how of the problem. Note that when can be particularly important as we can then look at error logs for more information.
- Steps to reproduce. How did the bug happen? What were you doing or trying to do at the time? This is important so we can reproduce the issue on the test site and investigate further.
- The text of any error messages you see.
- Where the bug is happening. A URL (when relevant) to the LR, student profile or page on the site.
- Information about your platform: browser, device and OS.
- Severity. Is it annoying? Is there a workaround? Or are things imploding because of this?
- Screenshots and anything else you can do to show us what is going on (e.g. demo on Skype or a screencast). Make sure you take a screenshot of the entire page, including the URL. Don't crop the image, because this can remove crucial information that can help us solve the problem.
- Your expectations in the situation.
Not all of this is relevant to all problems. If an LR is not saving when you click "save" then screenshots and telling us your expectations are by the by. However, a URL to the LR in question is essential.
---
Here are some details about how the site works and how we build and update it. It's in plain English. If anything doesn't make sense, please leave a comment.
Making things better
The general approach to how we do things is find a tool that does the job. If no such tool exists or it doesn't work like we want it to, find something that gets us close and then smash it into shape with a Dan hammer. The schedule is a good example of that strategy. TEFtalk also. They are built on top of existing code but finessed to get us what we want. There are varying degrees of complexity and cost involved here as most of these tools are not free.
Under the hood
The site is built on an open source platform called "Drupal". Drupal keeps things organised and humming. Functionality can often be added by installing extra bits of software on top of Drupal called "modules". This works OK if what you are looking for is popular and generic. This was how the site started, and the vast majority of that stuff was built by Matthew. Using Drupal is a way for us to outsource security updates and software development to the Drupal community. Drupal is very powerful, but not always super efficient. However, if we can add functionality and make updates this way, then it is fast and cheap. Lots of bug fixes come through this path. We can also make many simple changes to things through the Drupal user interface, such as when we add a new field to lesson records or profiles.
Much of what we do requires a level of customisation that Drupal cannot provide out of the box. That means we (Dan et al) need to write custom code that talks to the rest of the site to achieve what we want. The schedule and TEFtalk are examples of this. Dan is able to write things that are perfect for our purposes and run much faster than what is otherwise available. The downside is that Dan is costly, and this stuff takes a lot longer to make.
Over the top of Drupal is the front end, built with something called "Bootstrap". This is the look and feel of the site (colours, layout and such), and Matthew handles all of this currently. Bootstrap is much like Drupal in that a bunch of stuff that everybody wants is built into the framework.
We have a server and a database. The server is Drupal and Bootstrap and some other bits and pieces. That's the code. All of this talks to a database, where all the stuff the site needs to remember is stored. Drupal and Bootstrap pull data from the database and display it in your browser. The server and databse live on AWS in the cloud. The site is put together and then sent to your browser to display the website, This all goes via some other computers that remember bits that don't change so often so that things work faster (caching). Caching happens in your browser and on the site itself too. It's why we might ask you to clear your cache when something changes or is not working. We do this on the site too.
Development cycle
When changing the site, the general process is this:
- Specifications are defined, usually in conversation with Dan. "TEFtalk messages should be editable." "By who? How will that work? Do you want a little clicky pencil?"
- Code is written and tested on an offline version of the site (for example, I have a copy of the whole site on my work machine here at home that I can make changes to) and on test versions of the site on the internet.
- New code is added to the code base. We use software called "Git" (I know! The specific sofware we use is GitKraken, which is very punny) that tracks changes and makes sure things don't clash.
- Site is updated. We have a window when changes are pushed to the live site (the version of the site on the Internet we all use; i.e. this one). It's usually about 4AM JST weekdays. Most changes will not take the site offline.
Some things to note are that:
- Getting a clear specification can be very difficult if something is complex. Sometimes the specifications will be broken down into phases (as is the case with TEFtalk) and a basic verison (beta) rolled out for testing first, and then we iterate on that. You are also trying to guess how people will use a thing. This is not easy.
- Testing is not perfect. There are always edge cases. It is important to report bugs when you see them so we can fix them (see below about what a good bug report looks like).
- There are four of us working on the code base. Sometimes adding new code can throw other things out of whack (see 2). But this also means that if things go very sideways, we can always rewind the site and fix it. Git tracks all the changes made and you can undo dodgy code. AWS also takes a snapshot of the site every hour and that means we have redundancy when it comes to disaster recovery (thankfully we have needed that only once). This means minimal or zero data loss when things hit the fan.
- Updates can take time to get from start to finish. Something being "fixed at the next release" means that you might not see the changes immediately on this website. We tend to bundle stuff together as updating the site is a time-consuming process and it is more efficient to do a bunch of things in one hit.
If there is anything else about the site that is mysterious or you would like to understand better, let Matthew know.