Skip to content

Home

Jump to bottom Edit New page
Jean-Denis Vauguet edited this page May 31, 2013 · 53 revisions

Welcome! This wiki serves as the documentation for this project. You may also join Freenode#ruby-lang.org on IRC.

Want to contribute? Read this first :)

Much like a wiki, ruby-lang.org is editable by its users. Unlike a wiki, the edition does not take place on the website itself, but here, on Github. If you don't know much about git, head to the official website or the very good and to-the-point Github help.

The overhaul process is fairly straightforward:

  1. find something to edit/fix/update
  2. propose your change here
  3. wait for review and approval

The website is updated on a regular basis and your edits will show up when a team member triggers a new deployment.

How to contribute

If there is something you want to edit, the process is rather simple. First, create a Github account and log in. Then, it depends on whether you want to do a quick edit or something more involved.

Simple edits may be performed directly on Github, using the "Edit" button while browsing the file you want to edit:

  • head to the repository containing the website code
  • browse the files to display the one you want to edit (a description of the project structure is available here
  • click on "Edit" and make your changes
  • When everything looks fine, click the "Propose File Change" button
  • Provide a good rationale for your request, and click on "Send Pull Request" to complete the process

A new pull-request will be created with your changes. A member of the editorial team will review your request and eventually merge the edits in if all is good. If not, you will most likely receive some insights through a comment on your pull-request and will be automatically notified.

If you plan to perform regular and/or large-scale edits, you may want to clone the repository on your local machine instead:

Some conventions and guidelines

Commit messages

  • Commit messages must be in English.
  • The affected translation should be mentioned in the commit message.

Examples:

  • "Fix typo on en/about"
  • "Add latest news posts (de)"

Corrections on translated site

When you find an error on a translated site that is not language specific --like for example a typo in a code snippet-- consider opening an issue or pull request for the English site, that essentially serves as "master" for the various translations.

Notes for translators

When translating pages and news posts the directory structure and filenames of the English site should be kept. This makes it easier to find and compare corresponding pages and news posts. (Posts are located in the news/_posts/ directory of the respective language.)

So, simply copy the original page or post to the corresponding directory for your language and start translating!

  • Keep the original filename.
  • Keep the original author and publication date in the front matter.
  • Remember to set the lang variable to the correct language code.

Notes for maintainers

Branches and merging

Use feature branches.

Preview your changes before merging (bundle exec rake preview).

Do never merge the modified master branch into your feature branch. Merge your feature branch into master (possibly after rebasing it onto master).

And remember to always fetch the most recent changes from the remote master branch before merging.

If you are not sure about your changes, you can also push your feature branch and open a pull request for discussion.

Issues and pull requests

When reviewing issues or pull requests, maintainers should examine whether the reported problem applies to their language only, or to all translations, or also to the en or ja versions, and act accordingly.

Creating a new post

To create a new post, use e.g.

rake new_post:en

which will create a template for a news post for en. Then rename the file to contain an appropriate title (but do not change the date part) and start typing!

Note: For translations you should simply copy the original post to the appropriate directory, keeping the filename.

How to get analytics account.

If you hope to get permission to access google analytics of ruby-lang.org, you can create an issue and mention to @hsbt.

Insights

Add a custom footer
Add a custom sidebar
Clone this wiki locally