<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css" style="display:none;"> P {margin-top:0;margin-bottom:0;} </style>
</head>
<body dir="ltr">
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
Patrick,</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
I need update petsc manual on DMNetwork, but do not know how to proceed. I tried your suggested steps:</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<span style="margin:0px;font-size:15px;font-family:"Segoe UI", "Segoe UI Web (West European)", "Segoe UI", -apple-system, system-ui, Roboto, "Helvetica Neue", sans-serif;color:rgb(32, 31, 30);background-color:rgb(255, 255, 255)">1) go to the docs page you want
to edit on<span> </span><a href="http://docs.petsc.org/" target="_blank" rel="noopener noreferrer" data-auth="NotApplicable" style="margin:0px">docs.petsc.org</a></span>
<div style="margin:0px;font-size:15px;font-family:"Segoe UI", "Segoe UI Web (West European)", "Segoe UI", -apple-system, system-ui, Roboto, "Helvetica Neue", sans-serif;color:rgb(32, 31, 30);background-color:rgb(255, 255, 255)">
2) select the version you want (usually "main") in the black ReadTheDocs box in the lower right</div>
<span style="margin:0px;font-size:15px;font-family:"Segoe UI", "Segoe UI Web (West European)", "Segoe UI", -apple-system, system-ui, Roboto, "Helvetica Neue", sans-serif;color:rgb(32, 31, 30);background-color:rgb(255, 255, 255)">3) 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)</span><br>
</div>
<div style="font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div style=""><font color="#201f1e"><span style="font-size: 15px;">I do not understand 3). Can you give a tutorial demo in next petsc meeting? </span></font></div>
<div style=""><font color="#201f1e"><span style="font-size: 15px;">Hong</span></font></div>
<div id="appendonsend"></div>
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" style="font-size:11pt" color="#000000"><b>From:</b> petsc-dev <petsc-dev-bounces@mcs.anl.gov> on behalf of Patrick Sanan <patrick.sanan@gmail.com><br>
<b>Sent:</b> Wednesday, March 3, 2021 12:23 AM<br>
<b>To:</b> Jed Brown <jed@jedbrown.org><br>
<b>Cc:</b> Satish Balay via petsc-dev <petsc-dev@mcs.anl.gov><br>
<b>Subject:</b> Re: [petsc-dev] Commit squashing in MR</font>
<div> </div>
</div>
<div class="" style="word-wrap:break-word; line-break:after-white-space">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).
<div class=""><br class="">
</div>
<div class="">There is a section on squashing but it's currently a bit buried, and the advice in this thread is probably more useful/current</div>
<div class=""><a href="https://docs.petsc.org/en/main/developers/integration/#squashing-excessive-commits" class="">https://docs.petsc.org/en/main/developers/integration/#squashing-excessive-commits</a></div>
<div class=""><br class="">
</div>
<div class="">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:</div>
<div class=""><br class="">
</div>
<div class="">- go to the docs page you want to edit on <a href="http://docs.petsc.org" class="">
docs.petsc.org</a></div>
<div class="">- select the version you want (usually "main") in the black ReadTheDocs box in the lower right</div>
<div class="">- 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)</div>
<div class="">- if you get feedback on your MR and need to update, or notice a typo, I *think* this will work:</div>
<div class=""> - click on the last commit of your new branch</div>
<div class=""> - find the offending file</div>
<div class=""> - click on "edit at @deadbeef123"</div>
<div class=""><span class="x_Apple-tab-span" style="white-space:pre"></span>- change the branch *back* to your branch in the pulldown</div>
<div class=""><span class="x_Apple-tab-span" style="white-space:pre"></span>- click "edit"</div>
<div class=""><span class="x_Apple-tab-span" style="white-space:pre"></span>- back in your MR, edit to "squash commits"</div>
<div class=""><br class="">
</div>
<div class="">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).</div>
<div class=""><br class="">
</div>
<div>If you want a full preview, you can</div>
<div><br class="">
</div>
<div>1. Build the Sphinx docs locally from your branch, either with</div>
<div><span class="x_Apple-tab-span" style="white-space:pre"></span>- "make sphinx-docs-all LOC=$PETSC_DIR" (you may need to add PYTHON=python3, since this relies on Python 3.3+ for venv) </div>
<div><span class="x_Apple-tab-span" style="white-space:pre"></span>- 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</div>
<div><br class="">
</div>
<div>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.</div>
<div><br class="">
</div>
<div><br class="">
</div>
<div><br class="">
<blockquote type="cite" class="">
<div class="">Am 03.03.2021 um 05:32 schrieb Jed Brown <<a href="mailto:jed@jedbrown.org" class="">jed@jedbrown.org</a>>:</div>
<br class="x_Apple-interchange-newline">
<div class=""><span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important">Satish
Balay via petsc-dev <</span><a href="mailto:petsc-dev@mcs.anl.gov" class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; orphans:auto; text-align:start; text-indent:0px; text-transform:none; white-space:normal; widows:auto; word-spacing:0px">petsc-dev@mcs.anl.gov</a><span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important">>
writes:</span><br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<blockquote type="cite" class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; orphans:auto; text-align:start; text-indent:0px; text-transform:none; white-space:normal; widows:auto; word-spacing:0px; text-decoration:none">
On Wed, 3 Mar 2021, Blaise A Bourdin wrote:<br class="">
<br class="">
<blockquote type="cite" class="">Hi,<br class="">
<br class="">
This is not technically a petsc question.<span class="x_Apple-converted-space"> </span><br class="">
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.<br class="">
<br class="">
Anybody wants to pitch in, or explain me how to do this?<br class="">
</blockquote>
<br class="">
To squash commits - I use the 'squash' action in 'git rebase -i HASH' and figure out the HASH to use from 'gitk main..branch'<br class="">
<br class="">
[as git rebase requires the commit prior to the first commit of interest]<br class="">
<br class="">
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<br class="">
[and its not really specific to petsc workflow]<br class="">
</blockquote>
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important">You
can do it in one line, without changing the base:</span><br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important"> git
rebase -i $(git merge-base main HEAD)</span><br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important">An
alternative is</span><br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important"> git
rebase -i main</span><br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<br class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none">
<span class="" style="font-family:Helvetica; font-size:12px; font-style:normal; font-variant-caps:normal; font-weight:normal; letter-spacing:normal; text-align:start; text-indent:0px; text-transform:none; white-space:normal; word-spacing:0px; text-decoration:none; float:none; display:inline!important">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.</span></div>
</blockquote>
</div>
<br class="">
</div>
</body>
</html>