Update root readme adding key features, repo structure details, user uide reference, jira reference, details for repo clarity.

[sumobrian]

Description

Objective: Revise the root README.md file of the opensearch-migrations project to provide a comprehensive overview and detailed documentation, enhancing clarity and usability for users and contributors. Provide references to other READMEs in the repo.

Tasks Completed:

• Rename the Title.
• Add a Detailed Table of Contents.
• Update the Overview Section.
• Identify Key Features.
• Update Supported Versions and Platforms.
• Add Issue Tracking Information.
• Detail the Project Structure.
• Include a reference to User Guide.
• Add Getting Started Instructions.
• Reorignize the Development Section.
• Update Contributing Guidelines.
• Detail Publishing Instructions
• Add Acknowledgments.
• Remove Release Section.
• Correct Spelling and Grammar Errors.
• Improve Formatting and Consistency.
• Enhance Readability.
• Verify External References.

Issues Resolved

JIRA MIGRATIONS-2081

Is this a backport? If so, please add backport PR # and/or commits #

Testing

Verified links do not return 404s and that targets work as expected. The gradle targets need to be updated. Ideally gradlew build would build the complete solution. I opened a bug to make this change.

Check List

• New functionality includes testing
  • All tests pass, including unit test, integration test and doctest
• New functionality has been documented
• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.19%. Comparing base (0b08287) to head (564ea9c).
Report is 25 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1066      +/-   ##
============================================
+ Coverage     80.16%   80.19%   +0.02%     
- Complexity     2744     2863     +119     
============================================
  Files           367      383      +16     
  Lines         13743    14333     +590     
  Branches        949      988      +39     
============================================
+ Hits          11017    11494     +477     
- Misses         2149     2245      +96     
- Partials        577      594      +17     

Flag	Coverage Δ
gradle-test	78.21% <ø> (+0.13%)	⬆️
python-test	90.24% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[peternied]

Did a more detailed read of the readme, minor comments. Looks good to merge when you are ready, thanks!

[peternied]

There isn't any workflows that allow for downgrades. Is this a more idealized version of what the toolset can support or something that we want to promote as possible in the tool today?

[peternied]

I'd recommend removing this bullet until we've got more concrete support and validation in place.

[sumobrian]

Are you concerned about this specific migration path? This solution is recommended for users who want to move from versions greater than 7.10.2 back to 7.10.2.

[peternied]

Local docker doesn't work in a number of scenarios, I'd recommend pulling it from this list. By following the developer guide this is technically possible, but we haven't made an effort to make sure this is a good user experience.

[sumobrian]

While this may not be consistent across the solution, it’s crucial to support it. This approach enables rapid development and allows others to test the solution without fully committing to using it in the cloud. It also keeps the solution flexible for broader community adoption. We encourage users to explore these options and open issues if they encounter any challenges. This feedback not only helps improve the solution but also enhances the onboarding experience for everyone.

[gregschohn]

It does work for a number of scenarios and we have at least one engagement that leveraged this, especially in their early development. We should be striving to get a solution that any student or developer could stand up and test anywhere.

Instead of pulling this out, we should open up issues for where this doesn't work and we can track them. My guess is that K8s work can subsume all of this, but we'll run into this case in the future if we don't hold all of our projects to the same standard of building for at least two deployment environments. This documentation is the only thing that we have to uphold that contract.