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.  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: [email protected]
