Shazwazza opened a new issue #396: URL: https://github.com/apache/lucenenet/issues/396
Decided to create a central discussion about this here instead of all of the ideas getting lost in various threads :) Here's some found previous notes - https://github.com/apache/lucenenet/issues/282#issuecomment-635345730 (note: a lot has changed from this discussion to now!) - https://github.com/apache/lucenenet/pull/393 - https://github.com/apache/lucenenet/pull/231 - https://github.com/apache/lucenenet/pull/229#issuecomment-520831453 (scroll down to the "code samples" heading) The issue is: We have a [conversion program](https://lucenenet.apache.org/contributing/documentation.html#api-docs) that converts the Lucene (java) docs to a doc format that we can use for Lucene.Net. Each time this is run it will overwrite our docs files. This means that any manual updates made to these docs files such as fixing spelling mistakes and more importantly code snippets would just be overwritten. ## I have a simple proposal In various old threads we had some complex proposals but none of these are 'perfect' and won't cater very well for things like spelling mistakes. Instead of inventing some system, we can simply use Git: * We have a branch for each lucene (java) docs conversion that we plan to do * currently this is just one: 4.8.1. This branch can be called something like `docs/converted/4.8.1` and created from `master` * These `converted` branches are the only branches we ever execute the `JavaDocToMarkdownConverter` conversion program. * So currently, we would run `JavaDocToMarkdownConverter` once we create this branch. There will probably be no changes now since we've already executed this in master. * Merge the `converted` branch to the master branch * Make any required changes to the master branch docs files * 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. We won't be running this conversion program that often so the amount of merging would be minimal and we'd only have merge conflicts on files that we've changed that have large conflicts with changes we've made in the converter ... which would be quite rare so I don't foresee a lot of work with a Git merge. Some basic rules to this: * We will never merge into a `converted` branch from master since this will mean merge conflicts are not triggered and everythig would just be overwritten again * When we start working on a newer version of Lucene.Net, a new `converted` branch will be created from the current `converted` branch and the conversion is run there for the new lucene version. @NightOwl888 Any thoughts on that? ---------------------------------------------------------------- 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]
