This is assuming that you're new to Ruby and Rails (and the MVC design pattern that comes with it), but you have programming experience. First, some orientation:
Ruby is the programming language that QPixel is written in. It's object-oriented, interpreted, and quite like Python in some ways — if any of that makes any difference to you.
Bundler is Ruby's package system. Ruby packages are called gems, and the Gemfile is a file in the root of the project that holds a list of gem dependencies. You can install all dependencies using
Rails is a gem that provides a web framework for Ruby. Ruby has a number of gems that provide web frameworks; Rails is one of the most popular. It's fairly heavy-weight in terms of structure and learning curve, but it's also flexible, configurable, and well suited to larger applications.
MVC (Model-View-Controller) is the design pattern that Rails uses, which in part dictates the file structure of the project.
Understanding the design pattern and the file structure are key to understanding how to work with the QPixel code, and they're very much linked. The root of the QPixel repository (currently) contains these directories (excluding build config):
app/ contains app code: code that controls how the app works and behaves.
bin/ contains binaries for various gems - you can ignore this.
config/ contains Rails and environment configuration. You can usually ignore this.
db/ contains database setup/change information, complex SQL-only queries, and seeds.
img/ contains images for the new-user tutorial.
lib/ contains library extension code. You can usually ignore this.
public/ contains static content and assets.
scripts/ contains Ruby scripts for various tasks (both app-called and developer utilities).
test/ contains unit testing code. See How do I write a new test case?
For most changes that involve app presentation or behaviour, you want the
app/ directory, which contains:
assets/ contains CSS and JS
controllers/ contains controller code
helpers/ contains useful helper methods
mailers/ contains Rails' "mailers", which handle email sending
models/ contains model definitions
views/ contains view HTML
At this point you start to need a basic understanding of the MVC pattern to figure out where to go next.
- The Model represents the database. There's a model file for each type of data we have, each backed by a database table. These define what fields and methods are available on each type of data. There's a model for
AuditLog, etc etc.
- The View is what the user sees: the HTML structure for the user interface.
- The Controller links the two together: every URL is handled by a controller method, which handles the incoming request, retrieves any data necessary and provides it to the view, and performs any necessary changes or operations.
That should give you an idea for the overall structure of the project. Where exactly you need to go depends on what you want to do/what you're working on. For instance, if you're fixing a typo (i.e. something the user sees), you probably want a view file. If you want to change what happens (i.e. app behaviour), you probably want a controller, and/or you may need to make changes to a model to help support what you're doing.
Take issue #272 for an example. We want to add a link to each individual moderator tool page back to the moderator tools home.
In this case, we want to add a UI element. It doesn't require any additional operations to be performed or any changes to data or database structure — it's purely HTML. That means we're looking for a view file.
Moderator tool pages are handled by the
moderator controller, so the views for them are in
index.html.erb is the home page itself, so doesn't need an extra link. To each of the other files there, we can add a link at the top.
Instead of writing the HTML ourselves (i.e.
<a href="/mod">Back to tools</a>), we'll get Rails to do the work. We can call
link_to to get Rails to generate an
<a> tag; we'll use
moderator_path to ask for the correct URL, and we can pass in any other attributes we need. Any Ruby code we want to use is enclosed in
<% %> marks so that it gets preprocessed. Finally, we want something like this:
<% link_to moderator_path, class: 'has-font-size-small' do %>
« Back to moderator tools
<% end %>