Версии. Changelog. Обновления

[wc3banderlog]

Добрый день!
На данный момент пишу API для сайта, но так как им пользуются сторонние разработчики встал вопрос в написании документации и ведении версий.

Хотел бы спросить, кто и как это осуществляет? Какими инструментами вы пользуетесь?
Рабочий пример, в API внесены изменения, необходимо обновить документацию и предоставить changelog, как вы решаете эти вопросы? Записываете на бумаге? или просто пробегаетесь по всем изменениям в новой версии и уже затем все фиксируете в changelog?

[monolithed]

Рабочий пример, в API внесены изменения, необходимо обновить документацию и предоставить changelog, как вы решаете эти вопросы

Только так:

http://example.com/api/1/method=...

changelog-файлы нужны для вас, а не для тех кто будет испоьзовать ваше API.
Никто не будет ежедневно заходить на ваш сайт чтобы проверить изменили ли вы API

[wc3banderlog]

http://example.com/api/1/method=...

Пусть так, тогда опять же, кто как ведет changelog-и?

[monolithed]

Пусть так, тогда опять же, кто как ведет changelog-и?

Лог должен вестить автоматически.
Если представить что есть файл HISTORY.md:

# ECMAScript 6

ECMAScript 6 Harmony polyfil

### 0.0.0 / 2012-08-25
* Initial commit

### 0.0.1 / 2012-08-26
* Added new `eg` operator for the egal comparison (using Object.is(x, y))

В данном случае, чтобы получить такие записи в файле достаточно добавить соответствующий хук или алиас вида:

[alias]
      release = !git commit -am $1 && \
                     git tag -a $1 -m $2 && \
                     git push --tags && \ 
                     echo -e "### $1 /" $(date '+ %Y-%m-%d %H:%M:%S') "\n$2" >> HISTORY.md

Соответственно добавляем версионирование (тег и лог) так:

git release 0.0.1 'комментарий'