Markdown Usage in Your Project

What it means ?

It means to use Markdown formatting and Markdown files to enhance your projects, more precisely the management around it.

Markdown synthax is essentially used for formatting raw text into a bit more sexy one (This file is MD formatted !). The Mardown file extension is .md or .markdown (or nothing if you want).

Where to use it in your projects ?

Some files in a project are often forget, by mistakes, because it can do a lot more than just look a project like-a-pro.

For example, the README.md file is important for internal use; it gives to a incoming dev all the tools to quickly understand and efficiently your project.

CHANGELOG.md is the other file your MUST feed ! This is the file you'll never look at, but if sometime you need a quick look at the project's history, CHANGELOG.md is here to give you raw, efficient and simple informations.

Both of these files must be directly in the root directory AND must be followed in your git/svn/mercurial versioning tool.

README.md

A README.md file could be a very very long one!

Some informations are critics, other optionnals. Let's have a look on what you MUST write in your README.md file:

Name of your project
Description of all the project in 2~3 lines
Give a HOW-TO to grab the code (wich soft you have to use, repos, versioning tools ... etc)
If it's a library or a framework, give a HOW-TO to explain how to implement it
If it's a standalone project, give a HOW-TO to explain how to run it
Explain (or a link) to grab the doc.

You can optionaly add others stuffs, such as:

Give project's copyrights. (or a link to LICENSE.md)
Give the name of all dev's team (or a link to AUTHORS.md)
Give a HOW-TO to access issue's database (JIRA for ex)
Give a brief history of the project (main released versions only, CHANGELOG.md is here for further details)
Give , if needed, legal notices (ex for cryptographic stuffs)

At this point, your README.md is complete: any new developer how want to start with this project have all the clues and informations to deal with !

CHANGELOG.md

A CHANGELOG.md file is all your version historic, but a digest one ! Its aim is to quickly find which commit you are looking for.

It's very frustrating to generate a CHANGELOG.md during the project, but keep in mind: it's not for you, it's for the others!

There isn't universal template for this file but you need to write down here some "must have" informations like:

Give like a subtitle all majors and intermediates versions (minor versions can be placed in a developer CHANGELOG.md)
Give for each event its aim, an explanation, and its final commit short number (a link to your repo can be useful)

Aims are one-word stuff into brackets:

Fix
JIRAFix
Feature
Security

So an event can looks like:

TableView in ANN-01 doesn't crash anymore when you refresh it -> 95f32s5b

Markdown code is:

- [Fix] TableView in ANN-01 doesn't crash anymore when you refresh it -> [95f32s5b](http://www.google.com)

Here is a simple but efficiant template for a CHANGELOG.md file:

## 1.8.0 (unreleased)

Features:

  - add support for SVN sources -> [95f32s5b](http://www.google.com)
  - add metadata allowed_push_host to new gem template -> [95f32s5b](http://www.google.com)
  - adds a `--no-install` flag to `bundle package` -> [95f32s5b](http://www.google.com)

## 1.7.0 (2014-08-13)

Security:

  - Fix for CVE-2013-0334, installing gems from an unexpected source -> [95f32s5b](http://www.google.com)

Features:

  - Gemfile `source` calls now take a block containing gems from that source -> [95f32s5b](http://www.google.com)
  - added the `:source` option to `gem` to specify a source -> [95f32s5b](http://www.google.com)

Fix:

  - warn on ambiguous gems available from more than one source -> [95f32s5b](http://www.google.com)

## 1.6.5 (2014-07-23)

Bugfixes:

  - require openssl explicitly to fix rare HTTPS request failures -> [95f32s5b](http://www.google.com)

The "unreleased" version is the short-term roadmap which says: Yep we are working on a new version, we did these stuffs yet

CHANGELOG.md is a really important file which will help new devs/teams, managers to know what's inside the box now.

DEV CHANGELOG.md

A dev CHANGELOG.md is optional. It "markdowned" your version's history. This has been developed/think for git but can be studied for other versioning tools. It's a long file and can looks like this (thousand times longer):

2014-05-12 Version 1.1.10  
===========================
* 2014-07-03 [JIRA] BFIEWALBNP-782 - Paylib FAT iOS/Android vert/bleu: wording pop up confirmation désactivation et titre rubrique désactivation depuis MOD  
* 2014-07-02 minor improvements  
* 2014-07-01 pull/push common  
* 2014-07-01 [JIRA] BFIEWALBNP-772 - Paylib FAT iOS/android vert/bleu: tentative de réactivation du wallet avec MPIN bloqué  
* 2014-07-01 [JIRA] BFIEWALBNP-674 Paylib INAPP iOS Vert: design des boutons &quot;annuler&quot; et &quot;retour&quot;  
  2014-04-20 Version 1.1.9  
===========================
* 2014-05-28 [JIRA INAPP] BFIEWALBNP-670 Paylib FAT IOS Vert: libellés carte par défaut
* 2014-05-28 [JIRA INAPP] BFIEWALBNP-653 Mes factures/Paylib FAT IOS Vert/Bleu: changement d&#39;adresse mail  
* 2014-05-27 [InApp] ECBMode Encryption FDC

Again, this is optional, but if you want a summary file like this, there is some tool to automatically generate this. For UNIX system, There is git-changelog. Here is how to use it:

Put the file git-changelog somewhere in your PATH.
cd into your git project
execute git changelog > CHANGELOG.md
see CHANGELOG.md

Hook System

A brief paragraph to introduce hook system in git. Hooks are plugins to git, which directly interfer with git settings. In our case, we can use a hook to tell git:

On each commit, check user message format. if it's well formatted, commit, either reject it and notify the user.

Hooks are directly in the .git/hooks directory of your project and contain example.

To do something by checking a commit, we have to use the commit-msg.

More explanations and example on this page !

-- @JulienGdt

juliengdt/HowTo_Markdown.md