lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [lucenenet] NightOwl888 commented on issue #396: Idea on how to handle manually editing the docs files while keeping the automated conversion
Date Wed, 25 Nov 2020 14:04:48 GMT

NightOwl888 commented on issue #396:
URL: https://github.com/apache/lucenenet/issues/396#issuecomment-733726020


   I agree this sounds simpler to manage than other ideas that have been kicked around, provided
the procedure is documented in the [contributing section of the web site](https://lucenenet.apache.org/contributing/index.html)
so we never forget how to manage it.
   
   Implementing this procedure would close #283 and allow us to begin working on #284 immediately
(and allow us to accept PRs to update API documentation).
   
   However, the tag `docs/converted/4.8.1` sounds like a finished product rather than a half-way
point which is what it actually is. Perhaps one of the following would be more descriptive?
   
   - `docs/converted2markdown/4.8.1`
   - `docs/markdown-converted/4.8.1`
   - `docs/raw-converted-markdown/4.8.1`
   
   ### Changes to JavaDocToMarkdownConverter
   
   Since `JavaDocToMarkdownConverter` is only executed against the `converted` branch, any
changes to it must also be committed to the `converted` branch. And being that merges only
happen in one direction, changing it in the `master` branch would need to be strictly prohibited.
   
   Perhaps the simplest way to enforce this would be to remove git tracking for `JavaDocToMarkdownConverter`
from the `master` branch and add it to `.gitignore` on the `master` branch, but keep both
enabled on the `converted` branches. If we follow the same conflict resolution pattern as
the [`nbgv prepare-release`](https://github.com/dotnet/Nerdbank.GitVersioning/blob/master/doc/nbgv-cli.md#preparing-a-release)
command uses for the `version.json` file with our `.gitignore` file, we can prevent these
changes from creeping their way back onto `master` when merging into it.
   
   > If we need to re-run `JavaDocToMarkdownConverter` because we've made some fixes to
it to fix some conversions, formatting, etc... we re-run this on the converted branch, then
merge changes to the master branch. This will trigger a bunch of merge conflicts which can
be resolved by Git merge.
   
   By that I hope you mean [`git mergetool`](https://git-scm.com/docs/git-mergetool). I use
it with Git for Windows in combination with [Beyond Compare](https://www.scootersoftware.com/support.php?zz=kb_vcs#gitwindows),
and it makes dealing with conflicts much quicker and easier.
   
   The "LOCAL", "BASE", and "REMOTE" branches visible side by side as well as a way to quickly
scroll to each merge conflict. The scrollbars are linked so you see the same section in each
pane when you scroll one of them. There are color coded arrows to quickly inject different
blocks/lines of text or for more complicated edits manual editing is also allowed. Beyond
Compare Pro also has features that allow ignoring of "unimportant changes" such as whitespace
or code comments, which make some changes easier to deal with.
   
   ![image](https://user-images.githubusercontent.com/1538288/100231245-546daa00-2f59-11eb-9a5e-e162eaad09da.png)
   
   In this example, I am merging `master` into the current branch. The head of `master` is
displayed on the right, the current commit of the current branch is displayed on the left,
and "BASE" is what the current branch looked like prior to the current commit. The bottom
section is a "best guess" of how to merge it, and around 40% of the time it guesses right.
   
   At the end of the operation of a file, it creates a backup of the merge conflict in a file
with a `.orig` extension added to the original, so if you get it wrong on the first try there
is a way to go back and fix it manually.
   
   It takes a little getting used to, but it is much quicker to pop in a block of text by
clicking a colored arrow or to resolve a conflict by clicking on an exclamation point than
going through the blocks in the raw source file that git creates.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



Mime
View raw message