Linking documentation to Git commit comments
Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a format useful for inclusion in the projects documentation - history, changelog, or users manual as the case may be, it would be nice to link to the commit comments rather than retype, or copy/paste, them into the relevant documents. How do I create, and maintain, those links while also being able to select which ones are included in which documentation streams (i.e.: users manual, history, specifications, maintenance manual, etc.)?
Of note here is that while git is known for software development, it is not limited to that. It is equally useful for any system where multiple contributors need to coordinate, and track, their efforts. Such alternatives include a business presentation developed by a team, a textbook with multiple authors, and a research project - both data collection and reports.
Additional information:
The git repository is always available locally, though not always on the web (such as on GitHub). As such, a method which relies on the API developed for/at a specific web host is probably not usable. Though there are some rich features available in those APIs.
The documentation itself might be in a git, and often parts of it will be, though neither is a guarantee. Only the git commit comments are assured of being in the git, wherever it is hosted. The parts of the docs in a git are in markdown, however they are created. The majority of the time, the bulk of the document writing is done in a graphical word processor (MS Word, LibreOffice Writer, etc) and can be saved as either XML or RTF, though the preference is for DocBook XML format.
The tool to use is subject to change, this ability will be part of the decision process. The output formats are primarily PDF and HTML, though markdown is useful at times as well. The commit comments themselves are either reformated into the body of the documentation as a paragraph or annotation, or kept as-is (raw text) for an information bubble or footnote, depending on the target document, and the project objectives.
The key objective is to have the tool "pull" the comments into the documentation, dynamically by preference, rather than having to either retype them by hand, or copy/paste from the git to the documentation source.
This post was sourced from https://writers.stackexchange.com/q/33535. It is licensed under CC BY-SA 3.0.
1 answer
Identifying a commit
A universal identifier for each commit is its SHA1 — a 40 digit hexadecimal number, like this one:
3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33
This commit is from the Sphinx documentation builder's repo. The comment says:
Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353
Fix #4543: test for autodoc fails with python 3.5.3
A reasonable way to make a persistent link to a commit is to store its SHA1 and use it to access the commit through various interfaces — see examples below.
Getting commit details
Say, you're programming a system that builds documentation. You want to programmatically get the commit's message and add it to the changelog.
Command line and local repository
First option is when the code has filesystem access to the repository.
$ git show -s --format=%B 3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33
Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353
Fix #4543: test for autodoc fails with python 3.5.3
There are various --format options to get the required commit details.
API and remote repository
You can also use SHA1 to get the commit details from a remote repository. Say, you have a self-hosted GitLab installation and would like to get the commit's message via GitLab API. Here's what the GET request could look like:
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \
"https://gitlab.example.com/api/v4/projects/5/sphinx/commits/3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33"
Response is a JSON with lots of commit details.
Selecting commits
If you want to automatically select meaningful commits, you need some rule or convention for your team to mark such commits.
For example, many teams work with “git flow” or “GitHub/GitLab flow” methodologies, in which job is done in feature branches and then merged into a stable branch. Each merge results in a merge commit. If your team members write meaningful messages in merge commits, that's a good source for a changelog.
To get the merge commit messages, use git log --merges. In this example we get the hash (SHA1, %H), authoring date (%ad), and the commit message (%B), separated with newlines (%n):
$ git log --format='%H%n%at%n%B' --merges
You may want to pack the output in some convenient format, like JSON:
$ git log --merges --format='{%n "hash": "%H",%n "timestamp": %at,%n "subject": "%s"%n}'
{
"hash":3e0b5fb09d70d0457d7e5ae7892504f6e1b45f33,
"timestamp": 1517848081,
"subject": "Merge pull request #4556 from tk0miya/4543_autodoc_test_fails_with_py353"
}
...
The same list of --format options applies here.
This post was sourced from https://writers.stackexchange.com/a/33538. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads