Quaternion formalism comments and docs

[bogdan-tanygin]

Fixes #2964

Description of changes:

• code minor comment
• docs minor change
• bib ref to both

PR Checklist

• Tests?
  • Interface
  • Core
• Docs?

[codecov]

Codecov Report

Merging #3392 into python will increase coverage by <1%.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           python   #3392    +/-   ##
=======================================
+ Coverage      86%     86%   +<1%     
=======================================
  Files         538     538            
  Lines       25306   25306            
=======================================
+ Hits        21828   21830     +2     
+ Misses       3478    3476     -2

Impacted Files	Coverage Δ
src/core/rotation.cpp	100% <ø> (ø)	⬆️
src/core/electrostatics_magnetostatics/p3m.cpp	85% <0%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d40b456...427a5cd. Read the comment docs.

[jngrad]

The failed CI jobs have been restarted, it was a runner issue on our side. Sorry for the inconvenience.

The first 10 merge commits don't seem to add history and make the git graph more difficult to read. What would you think of rebasing the branch to have ee4232f after the last commit in the python branch?

Beside the proposed changes, this PR looks good to me.

[bogdan-tanygin]

The first 10 merge commits don't seem to add history and make the git graph more difficult to read. What would you think of rebasing the branch to have ee4232f after the last commit in the python branch?

in general, I agree. However, these merge commits are distributed over the whole 2019th year. Hence, they do not confuse the history graph so much (they are not a continuous sequence) and, also, I'm not sure how to rebase this safely (I've tried and have some suspicious feeling, maybe you could advise the safe commands). Nevertheless, I agree, next time I will not create new branches from my main branch, rather I will checkout directly from the Es. base. Also, I will merge updates using the --ff-only in case of conflicts absence. Hence, this will remove such commits further.

[jngrad]

Hence, they do not confuse the history graph so much

The issue with merge commits is they prevent me from cherry-picking your branch into the 4.1.3 branch. When this happens, I need to manually inspect the graph to see which commits belong to your branch vs. which commits come from elsewhere to craft a valid sequence of git cherry-pick commands.

I've tried and have some suspicious feeling, maybe you could advise the safe commands

The canonical way is to use the 3-commit rebase --onto feature: new base, old base, tip of the branch. The annoying part is that this command puts the result in a detached HEAD. Here's how to handle it:

git checkout quat-formalism-comments
# rebase commit range
git rebase --onto upstream/python ee4232f0b4c^ HEAD
# we are now in a detached HEAD, we'll store it in a new branch
git branch quat-formalism-comments-rebased
git checkout quat-formalism-comments-rebased
# optional: squash the 3 peer-review commits
git reset --soft HEAD~2
git commit --amend -m 'Apply code review feedback

Co-Authored-By: Jean-Noël Grad <[email protected]>'
# push force
git push -u -f origin quat-formalism-comments-rebased:quat-formalism-comments

This can also be achieved with a cherry-picking with git v1.7+:

git checkout -b quat-formalism-comments-rebased upstream/python
git cherry-pick ee4232f0b4c^..quat-formalism-comments
# optional: squash the 3 peer-review commits
git reset --soft HEAD~2
git commit --amend -m 'Apply code review feedback

Co-Authored-By: Jean-Noël Grad <[email protected]>'
# push force
git push -u -f origin quat-formalism-comments-rebased:quat-formalism-comments

I can do it for you if you want.

The squashing makes the code review history shorter. GitHub provides the Add suggestion to batch option to apply all code review suggestions in a single commit. This also avoids triggering the CI pipeline multiple times.

[bogdan-tanygin]

Hi @jngrad , thanks for the best practices sharing! It's useful.