ranqingsong / styleguide-and-faq

Includes the Styleguide and Frequently Asked Questions (FAQ)

Styleguide and FAQ

Build software better, together, now (QuantNet 2.0 @ GitHub)

We highly recommend that you first familiarize yourself with the Styleguide and the application of yamldebugger. They will help you to avoid typical problems and strengthen your sense of achievement.

This repository includes:

• Styleguide of Quantlets for first submission - Styleguide
• Frequently Asked Questions - FAQ
• How to format and upload your Quantlet to QuantNet 2.0 - Workflow
• Template for mandatory file in every QuantLet subfolder of a repository (see also Guideline II):
• metainfo.txt - Please format your added content according to YAML as described in the Styleguide. Thanks to your effort, we are able to automatically provide a standardized Readme.md to your repository.
• YAML parser debugger (yamldebugger) according to the QuantNet style guide: the R-Package yamldebugger may be freely used for testing and validating the own Quantlets bevore uploading them into https://github.com/quantlet . Mainly, it checks the validity of the YAML meta information and the completeness of the mandatory data fields as described in Styleguide

Guideline I:

• Abbreviations
  • Q = Quantlet
  • QNet = Quantnet
  • repo = repository
  • GH = GitHub

Guideline II:

• Every Q has to be in its own subfolder in the repository (see also Workflow).

  • Reponame/Qfolder1/files of Q1
  • Reponame/Qfolder2/files of Q2
  • Reponame/Qfolder3/files of Q3

• Some Examples:

  1. [MSM] (https://github.com/QuantLet/MSM) (Reponame: MSM, 12 Qfolders)
  2. [Psychological-diagnostics] (https://github.com/QuantLet/Psychological-diagnostics) (Reponame: Psychological-diagnostics, 1 Qfolder)
  3. [TimeVaryingPenalization] (https://github.com/QuantLet/TimeVaryingPenalization) (Reponame: TimeVaryingPenalization, 4 Qfolders)

Guideline III:

• Avoid blanks in the repository names!
• Avoid unnecessary special characters in the names of repositories, subfolders and Qs
• In case of doubt use the underscore character "_"
• Some good Examples:
  1. [big_data_analysis] (https://github.com/QuantLet/big_data_analysis)
  2. [MMSTAT] (https://github.com/QuantLet/MMSTAT)
  3. [Git2Q3-Collaboration] (https://github.com/QuantLet/Git2Q3-Collaboration)
• Some bad Examples:
  1. [lCARE-BTU-HU-] (https://github.com/QuantLet/lCARE-BTU-HU-) (unnecessary dash)
• Please note that repos with bad name notation will be excluded from final validation and importing into the [Visualization] (http://quantnet.wiwi.hu-berlin.de/d3/ia/). It's up to you to rename your repos accordingly. Actually, some special characters make the automatic processing impossible.