Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How does a newcomer to Ruby get oriented in the qpixel code? Question

+3
−0

I am new to Ruby (and Rails) and have just (finally) succeeded in setting up qpixel on my Mac. I headed over to our easy GitHub issues looking for something to use to get started, and then realized... wait, I don't know my way around this code base at all. There are presumably conventions about what goes where, what the architecture is, etc that would be obvious to someone more experienced than I.

Is there an overview of the project for people like me? Are there key files that I should look at first? I looked for internal documentation but it's not in an obvious place (like a "doc" directory). We do have an old wiki, but its focus is a little different (and did I say "old"?).

How do I get from an assertion on GitHub that an issue is "easy" to finding the right places in the code to start poking? If there are tools that make this easier (what's the normal IDE for Ruby?), I'm interested in that too.

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

0 comment threads

1 answer

+3
−0

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 bundle install.
  • 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.

File structure

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

MVC

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 User, Post, 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 app/views/moderator/. 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 %>
  &laquo; Back to moderator tools
<% end %>
History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »