Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users

Dashboard
Notifications
Mark all as read
Q&A

Linking documentation to Git commit comments

+2
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/33535. It is licensed under CC BY-SA 3.0.

0 comment threads

1 answer

+1
−0

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.


Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/33538. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!