enhance www/README.md #912
Conversation
hubyrod
force-pushed
the
www_readme
branch
4 times, most recently
from
3e5deac to
b6a4a7d
Compare
|
I think something got slightly messed up with a rebase or something, some of the changes for resolved comments are not applied, and there is a duplicate ```bash line. |
|
Did you check that things are in the desired state after the rebase recovery? It looks to me that the comments marked as resolved have still been undone in the current state of this branch. |
Co-authored-by: Josh Berdine <[email protected]>
www/README.md
Outdated
| git clean -Xdf # the actual cleaning | ||
| ``` | ||
|
|
||
| ### What if the hash is not in the commit message suggested along the process ? |
There was a problem hiding this comment.
At least in my experience, the observation that something is wrong is that git push asks for --force, which we shouldn't do. I don't actually understand the question of this FAQ, what is "the hash" it is referring to?
There was a problem hiding this comment.
What has happened in the past, is that the hash in the commit message is not the expected hash.
May be not well phrased. Let me suggest something different.
hubyrod
force-pushed
the
www_readme
branch
2 times, most recently
from
f2f9184 to
f3166e3
Compare
| [here](https://typedoc.org/guides/tags/). | ||
| The commit hash in the last line should be the hash of your commit in the skip repository. | ||
|
|
||
| > **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain incorrect commit hashes. |
There was a problem hiding this comment.
| > **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain incorrect commit hashes. | |
| > **Note**: If `make docs-publish` is run from a commit that is not (an ancestor of) `main`, the docs_site commit messages will contain unreproducible commit hashes. |
|
|
||
| ### Publishing Documentation | ||
|
|
||
| Before, commit your changes and send them for review |
There was a problem hiding this comment.
Up to you, but I would suggest:
| Before, commit your changes and send them for review | |
| First commit your changes and send them for review |
| ``` | ||
| This will suggest to run: | ||
|
|
||
| When reviewed and merged, you are ready to publish documentation to the live site: |
There was a problem hiding this comment.
Up to you, but I would suggest:
| When reviewed and merged, you are ready to publish documentation to the live site: | |
| Once reviewed and merged, you are ready to publish documentation to the live site: |
| ### What if my `docs_site` is not on the `main` branch ? | ||
| Clean up your repository is good idea at this point and then start the process again: | ||
| ```bash | ||
| git pull --rebase # ensure that your local docs_site submodule is up-to-date | ||
| git clean -Xdn # -n for a dry-run and double-check what's to be cleaned out | ||
| git clean -Xdf # the actual cleaning | ||
| ``` | ||
|
|
||
| ### What if the hash in the suggested commit message is not the hash of your commit? | ||
| You can get it from the skip repository: | ||
| ```bash | ||
| git rev-parse --short HEAD # supposingly it is the last commit of the branch | ||
| ``` |
There was a problem hiding this comment.
I don't mean to be difficult, but I still don't understand. I'm not sure if two potential issues are being mixed up. The two issues I am aware of are:
- The local docs_site submodule is behind the upstream one.
- There is one or more local commits that have not been merged into the upstream main branch.
For 1., the symptom is that the git push suggested by make docs-publish complains about needing --force. In this situation, we do not want to force push, but should instead update the docs_site submodule and regenerate the docs and try to publish again.
For 2., the symptom is that git merge-base HEAD origin/main is not equal to HEAD, which will lead to the commit message suggested by make docs-publish to contain a <commit> that is only local. In this situation we do not want to change that commit message, we want to make sure that the HEAD commit that we publish is an ancestor of origin/main.
So there are potential confusions in these FAQs:
- The solution for
docs_sitebeing out of date is to update the submodule. The cleaning is independent of docs, and is just a general issue due to missing dependencies in the build system that are sometimes encountered when updating across a bootstrap of the skiplang compiler or runtime system. - The FAQ is not clear. The hash in the suggested commit message is correct, it just might be that the commit is not merged into origin/main. The FAQ makes it sound like the commit message should be changed, but that is not the right action.
No description provided.