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

Much like a wiki, ruby-lang.org is editable by its readers. Unlike a wiki though, the editing process does not take place on the website itself; instead, it happens here, on GitHub. If you don't know about Git, head toGit's official website, or consult the very apt and to-the-pointGitHub help on Git.

Making changes to ruby-lang.org is quite easy:

1. find something to add/fix/update
2. propose your change here (how exactly? See below)
3. wait for a review and approval
4. enjoy once your change has been deployed!

The website is updated on a regular basis: your approved edits will show up when ateam member triggers a newdeployment (usually right after the edits have been approved).

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 tothe repository containing the website code
• browse the files to display the one you want to edit (a description of the project structure is availablehere
• 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 newpull-request will be created with your changes. A member ofthe 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 instead, so that you can work and preview on your local machine before submitting changes. Here's the process:

• head tothe repository containing the website code
• follow the instruction on the README (git clone and installation guidelines)
• Make your changeson a topic branch, usingmaintainer-friendly policies
• Follow the GitHub guide onpull-request to create a new request

• Always usefeature branches, never commit tomaster directly.
• Never mergemaster or other branches into your feature branch.
• Make commits of logical units. Feel free to usegit commit --amend and repush to fix open pull requests.
• Commit messagesmust bein English.
• They should beshort and descriptive. Reasoning or comments do not belong there; tiny changes (like fixed typos) do not need long explanations.
• Theaffected translation should be mentioned in the commit message, see the examples below.
• Try to follow "50/72 formatting"(first line: 50 characters or less, remaining text: wrapped at 72 characters).

Examples:

• "Fix code example on About page (en)"
• "Translate latest news posts (de)"
• "Fix typos (zh_cn)"

"Translated site" means, a version other than the mainstream English one.

When you find an error on a translated site that is not language specific--like, say, a typo in a code snippet-- consider opening an issueor pull request for the English site, that will essentially serve as the"master" issue for the various translations. Using checkboxes for languagesand notifying lang maintainers is a good way to go.

• Themarkdown on translated sites should be kept as close as possibleto the English site.

• Named link references: when links are removed or added to a page,the existing link numbers shouldnot be updated(in order to create a gapless sequence of numbers);this makes diffs between commits and also between the Englishand translated, not yet updated pages much more easier to read.

  For new links, shortdescriptive names are much preferred over numbers.

  (The link numbers originate from the migration of the site to Jekyll,where they were automatically created.)

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

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

• Keep the original filename.
• Keep the original author and publication date in the front matter.
• Remember to set thelang variable to the correct language code.
• Do not modify code examples (comments in code may be translated, though).

General hints:

• Use short but descriptive filenames.

  A good example is2014-10-27-ruby-2-1-4-released.md(note that the date part is obligatory).

• Use absolute URLs even for internal links (because of the RSS feeds).

To create a new post, use e.g.

rake new_post:en

which will create a template for a news post foren.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 postto the appropriate directory, keeping the filename.

News posts about vulnerabilities and other security issues mustbe tagged in the YAML front matter like shown below,in order to get included in the list on thesecurity/ page:

date: ...tags: securitylang: ...

Use feature branches.

Preview your changes before merging (follow the instruction on the README).

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

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

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

When reviewing issues or pull requests, maintainers should examine whetherthe reported problem applies to their language only, or to all translations,or also to theen orja versions, and act accordingly.

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

• Structure
• Team
• Deployment