[petsc-dev] Commit squashing in MR

[Patrick Sanan]

The whole section on git in the dev manual needs some attention. (It was moved there in the consolidation of docs we had scattered in various places, but hasn't been expertly updated yet). Ideal, I think, would be to find some good, external instructions and link to them, under the idea that we should only maintain things in our own docs that aren't adequately documented somewhere else. This might not be possible (since we had to create these instructions in the first place).

There is a section on squashing but it's currently a bit buried, and the advice in this thread is probably more useful/current
https://docs.petsc.org/en/main/developers/integration/#squashing-excessive-commits <https://docs.petsc.org/en/main/developers/integration/#squashing-excessive-commits>

If anyone wants to go in there and quickly update those docs, remember that you can do so all from web interfaces! This workflow still has some wrinkles, but for small changes I still think it's appealing:

- go to the docs page you want to edit on docs.petsc.org
- select the version you want (usually "main") in the black ReadTheDocs box in the lower right
- click "edit" in "on GitLab" and make your MR (name the branch with "docs-" to maybe get it to auto-build on ReadTheDocs, label with docs and docs-only)
- if you get feedback on your MR and need to update, or notice a typo, I *think* this will work:
       - click on the last commit of your new branch
       - find the offending file
       - click on "edit at @deadbeef123"
	- change the branch *back* to your branch in the pulldown
	- click "edit"
	- back in your MR, edit to "squash commits"

You can get a partial preview with the usual "preview" button, though not everything is interpreted correctly (but for things like links, it works fine).

If you want a full preview, you can

1. Build the Sphinx docs locally from your branch, either with
	- "make sphinx-docs-all LOC=$PETSC_DIR"  (you may need to add PYTHON=python3, since this relies on Python 3.3+ for venv) 
	- install the required Python packages yourself (e.g. pip install -r src/docs/sphinx_docs/requirements.txt), go to src/docs/sphinx_docs, run "make html", and look in _build/html

2. Build the Sphinx docs for your branch as a version on ReadTheDocs. There is currently an automation rule there that if your branch name has "docs-" in it, it should build (though I must admit I'm still not completely sure I understand exactly when RTD updates its information from GitLab). Or, if you have access, you can activate a new version yourself.



> Am 03.03.2021 um 05:32 schrieb Jed Brown <jed at jedbrown.org>:
> 
> Satish Balay via petsc-dev <petsc-dev at mcs.anl.gov <mailto:petsc-dev at mcs.anl.gov>> writes:
> 
>> On Wed, 3 Mar 2021, Blaise A Bourdin wrote:
>> 
>>> Hi,
>>> 
>>> This is not technically a petsc question. 
>>> It would be great to have a short section in the PETSc integration workflow document explaining how to squash commits in a MR for git-impaired developers like me.
>>> 
>>> Anybody wants to pitch in, or explain me how to do this?
>> 
>> To squash commits - I use the 'squash' action in 'git rebase -i HASH' and figure out the HASH to use from 'gitk main..branch'
>> 
>> [as git rebase requires the commit prior to the first commit of interest]
>> 
>> git provides many ways of modifying the branch (and the rebase topic is very generic) so I think its best to rely on proper git docs/tutorials
>> [and its not really specific to petsc workflow]
> 
> You can do it in one line, without changing the base:
> 
>  git rebase -i $(git merge-base main HEAD)
> 
> 
> An alternative is
> 
>  git rebase -i main
> 
> which gives you interactive rebase to replay on top of current 'main'. This does two things at once and changing the base for your branch is not always desirable.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20210303/1195e429/attachment.html>