Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (138 loc) · 7.45 KB

CONTRIBUTING.md

File metadata and controls

172 lines (138 loc) · 7.45 KB

Contributing to radanalytics.io

In general, all contributions should be made by forking this repository, making your changes on a feature branch, and proposing that feature branch as a pull request in GitHub.

This site is generated using the Jekyll framework, with several customizations to create the look and feel. Please reference their documentation for questions about the usage of jekyll features in your documents.

Review standards

For most changes that are proposed to this repository you will simply need to get approval by another community member. This includes all changes that cover things like grammar/spelling updates, bug fixes, and smaller articles.

When proposing larger changes (eg modifications to major style components, adding large tutorials, reorganizing content) you will need to get approval from 3 community members before a merge will occur. For convenience you may mention the @radanalyticsio/radanalytics-io team to get the attention of a larger group of reviewers. We recommend adding a reply comment to your review with text similar to @radanalyticsio/radanalytics-io ptal (ptal means "please take a look").

Testing out your changes locally

To test this site locally, you will need to have Ruby installed as well as the Bundler gem and the Bower application. This will make installing and running the site much simpler. With all the required development software installed, you should be able to run the site locally as follows:

$ gem install bundler
$ cd radanalyticsio.github.io
$ bundle install --path .vendor
$ bower install
$ bundle exec jekyll serve

At this point the site will be running and served locally at http://localhost:4000, with the server running any file changes will be automatically picked up and the site re-generated.

A note on Mac OSX development A common source of problems for Mac users when installing Jekyll's dependencies is the Nokogiri library. Should your bundle install run into trouble installing Nokogiri, please see the suggestions offered in the Nokogiri docs or consult Stack Overflow for other possible fixes.

Docker based testing

If you would prefer to use a self-contained environment for testing your changes, a Dockerfile is provided in the root of the project which will allow you to leverage the convenience of docker. To test your changes using this methodology run the following:

$ cd radanalytics.github.io
$ chmod -R go+rX .
$ docker build -t radanalytics.io .
$ docker run --rm -it -p 4000:4000 radanalytics.io

The site will now be served locally at http://localhost:4000

Adding a new tutorial

If you would like to propose a new application or example for inclusion in the tutorials section, there are a couple steps that need to be completed:

  1. Copy the _templates/application_or_example.adoc file to the _applications or _examples directory depending on its type and rename it to suite your tutorial's name.
  2. Edit your new tutorial AsciiDoc file with the appropriate information. (there is information in the example on what to provide)
  3. If your tutorial will require additional assets (images, slide deck, etc), create a directory for your tutorial documentation assets in the assets directory. This new directory should be named to match the value you provided in the page-link attribute entry in your tutorial document.
  4. Add any assets you will need (graphics, files, etc) to your assets directory.
  5. If your tutorial includes a lightning talk, copy the _templates/lightning directory into your assets directory. This directory contains the reveal.js slide deck template. Also ensure that the page-menu_items attribute entry contains the lightning value, this will create the proper menu link for the slide deck.
  6. Edit the index.html file for the lightning slide deck. (there is information in the file on what to provide)
  7. Commit the files to your feature branch and propose a pull request when you are ready.

Adding a new FAQ entry

The Frequently Asked Questions (FAQ) page is generated from the collection of documents stored in the _faqs directory. To add a new question/answer pair, simply do the following:

  1. Copy the _templates/faq.adoc file to the _faqs directory, and rename it to reflect your question.
  2. Edit the contents of the new file to contain your question, the title of the document will get converted to be used in the FAQ page.
  3. Commit the new file to your feature branch and propose a pull request when you are ready.

Adding a new "How do I" entry

The "How do I?" page is generated from the collection of documents stored in the _howdoi directory. To add a new question/answer pair, simply do the following:

  1. Copy the _templates/how-do-i.adoc file to the _howdoi directory, and rename it to reflect your question.
  2. Edit the contents of the new file to contain your question, the title of the document will get converted to be used in the "How do I" page.
  3. If you need to add media files for your entry, add them to the assets/howdoi directory.
  4. Commit the new file to your feature branch and propose a pull request when you are ready.

Adding a new presentation

The community page contains a list of presentations given by and about radanalytics related topics. If you would like to add your presentation to this list, please follow these instructions:

  1. Copy the _templates/presentation.adoc file to the _presentations directory and rename it to reflect the name of your presentation.
  2. Edit the contents of the new file to contain your presentation abstract and related information.
  3. Commit the new file to your feature branch and propose a pull request when you are ready.

Adding a new project

The projects page contains a list of the radanalytics hosted projects. If you would like to add a new project to this list, please follow these instructions:

  1. Copy the _templates/project.adoc file to the _projects directory and rename it to reflect the name of the project.
  2. Edit the contents of the new file to contain the project information and links.
  3. Commit the new file to your feature branch and propose a pull request when you are ready.

A note on front matter

Files that will be processed by jekyll contain a bit at the beginning referred to as front matter. This is a small section of YAML that contains variables which will be available to the processing engine. When creating your application documentation there are several front matter variables which will help with the proper display of your information. Please be careful to follow the instructions in the template about their usage.

A note on AsciiDoc AttributeEntry blocks

As the content of this repository is converted from Markdown to AsciiDoc, you might notice some changes in the way the front matter variables are handled. AsciiDoc documents may contain AttributeEntry blocks in their headers. These variables are used in a similar manner as the Jekyll front matter variables. Although these attribute entries and front matter can co-exist within the current deployment framework, the preference should be to always use AsciiDoc attribute entries when possible.