Bug: Rewrite hbck2 documentation using GPT
Status: Open | Priority: Major | Resolution: 
Created: 19/Aug/23 19:53

Just a thought, could we re-write the operator tools [README.md|https://github.com/apache/hbase-operator-tools/blob/master/hbase-hbck2/README.md] using GPT and make it better?

A sample paragraph re-written by ChatGPT is as follows:

Original:
{quote}
h3. Some General Principals

When making repair, make sure hbase:meta is consistent first before you go about fixing any other issue type such as a filesystem deviance. Deviance in the filesystem or problems with assign should be addressed after the hbase:meta has been put in order. If hbase:meta is out of whack, the Master cannot make proper placements when adopting orphan filesystem data or making region assignments.

Other general principles to keep in mind include a Region can not be assigned if it is in _CLOSING_ state (or the inverse, unassigned if in _OPENING_ state) without first transitioning via {_}CLOSED{_}: Regions must always move from {_}CLOSED{_}, to {_}OPENING{_}, to {_}OPEN{_}, and then to {_}CLOSING{_}, {_}CLOSED{_}.

When making repair, do fixup of a table-at-a-time.

Also, if a table is {_}DISABLED{_}, you cannot assign a Region. In the Master logs, you will see that the Master will report that the assign has been skipped because the table is {_}DISABLED{_}. You may want to assign a Region because it is currently in the _OPENING_ state and you want it in the _CLOSED_ state so it agrees with the table's _DISABLED_ state. In this situation, you may have to temporarily set the table status to {_}ENABLED{_}, just so you can do the assign, and then set it back again after the unassign. _HBCK2_ has facility to allow you do this. See the _HBCK2_ usage output.

What follows is a mix of notes and prescription that comes of experience running hbase-2.x so far. The root issues that brought on states described below has been fixed in later versions of hbase so upgrade if you can so as to avoid scenarios described.
{quote}
Re-written using ChatGPT:
{quote}*Some Basic Principles*

Ensure hbase:meta's consistency before attempting to fix any other type of problem, such as filesystem deviations. Issues related to filesystem or assignment should be addressed once hbase:meta is sorted out. If hbase:meta is awry, the Master cannot accurately allocate orphan filesystem data or region assignments.

Remember that a Region cannot be assigned if it is in a CLOSING state (or conversely, unassigned if in an OPENING state) without going through a CLOSED state first. Regions must always progress from CLOSED, to OPENING, to OPEN, to CLOSING, and then back to CLOSED.

Make repairs table-by-table.

Additionally, if a table is DISABLED, you cannot assign a Region. The Master logs will indicate that the assignment has been bypassed due to the table's DISABLED status. You might want to assign a Region because it is currently in the OPENING state, but you want it in the CLOSED state to match the DISABLED state of the table. In such cases, you might need to briefly change the table status to ENABLED to make the assignment, then switch it back after the unassignment. HBCK2 provides a facility for this. Please refer to the HBCK2 usage output.

The following notes and instructions come from the experience of running hbase-2.x so far. The underlying issues causing the states described below have been resolved in later versions of hbase, so upgrading is recommended to avoid these scenarios.
{quote}
 

Is this worth the effort? Or do others feel current doc is good and does not need any refinement?

It may require some effort, as we may only start with first commit with untouched document generated by ChatGPT, but then the draft would need to be worked upon, based on some proofreading by the contributor and reviewers.

Curious to know how others feel.

Also, Apache has some guidelines around using of generative ai tools at [https://www.apache.org/legal/generative-tooling.html]