Actually, I prefered option 2. But I want to know the risk or disadvantages about option 2.
On 2025/03/11 07:35:26 Qiming Teng wrote: > Hi, All, > > A great project needs great documentation. We have got some markdown > formatting issues for discussion. > This email/vote focuses on the proper way to format markdown files regarding > line wrappings. > We need to address some style consistency problems going forward, leaving the > history behind us. > > Let me try articulate this with an example borrowed from an existing document. > (Please 1. Ignore the syntax issues, if any; 2. Don’t treat this as a blame > to the original author.). > > Current style [Style 1]: > > ### Authentication for Hadoop Catalog > > The Hadoop catalog supports multi-level authentication to control access, > allowing different authentication settings for the catalog, schema, and > fileset. The priority of authentication settings is as follows: catalog < > schema < fileset. Specifically: > > - **Catalog**: The default authentication is `simple`. > - **Schema**: Inherits the authentication setting from the catalog if not > explicitly set. For more information about schema settings, please refer to > [Schema properties](#schema-properties). > - **Fileset**: Inherits the authentication setting from the schema if not > explicitly set. For more information about fileset settings, please refer to > [Fileset properties](#fileset-properties). > > The default value of `authentication.impersonation-enable` is false, and the > default value for catalogs about this configuration is false, for schemas and > filesets, the default value is inherited from the parent. Value set by the > user will override the parent value, and the priority mechanism is the same > as authentication. > > New style [Style 2]: > > ### Authentication for Hadoop Catalog > > The Hadoop catalog supports multi-level authentication to control access, > allowing different authentication settings for the catalog, schema, and > fileset. > The priority of authentication settings is as follows: catalog < schema < > fileset. > Specifically: > > - **Catalog**: The default authentication is `simple`. > - **Schema**: Inherits the authentication setting from the catalog if not > explicitly set. > For more information about schema settings, please refer to [Schema > properties](#schema-properties). > - **Fileset**: Inherits the authentication setting from the schema if not > explicitly set. > For more information about fileset settings, please refer to [Fileset > properties](#fileset-properties). > > The default value of `authentication.impersonation-enable` is false, > and the default value for catalogs about this configuration is false, > for schemas and filesets, the default value is inherited from the parent. > Value set by the user will override the parent value, > and the priority mechanism is the same as authentication. > > New Style [Style 3] > > ### Authentication for Hadoop Catalog > > The Hadoop catalog supports multi-level authentication to control access, > allowing different > authentication settings for the catalog, schema, and fileset. The priority of > authentication > settings is as follows: catalog < schema < fileset. Specifically: > > - **Catalog**: The default authentication is `simple`. > - **Schema**: Inherits the authentication setting from the catalog if not > explicitly set. For more > information about schema settings, please refer to [Schema > properties](#schema-properties). > - **Fileset**: Inherits the authentication setting from the schema if not > explicitly set. For more > information about fileset settings, please refer to [Fileset > properties](#fileset-properties). > > The default value of `authentication.impersonation-enable` is false, and the > default value for > catalogs about this configuration is false, for schemas and filesets, the > default value is > inherited from the parent. Value set by the user will override the parent > value, and the priority > mechanism is the same as authentication. > > The differences? > > > * Style 1: Don’t break long sentences or even paragraphs. Let the IDE or > your editor do it for you. > * Style 2: Break long lines at their natural boundary (punctuators, > periods, subclause if necessary), for readability. > * Style 3: Always break sentences at a hard linewidth (say 120 > characters). > > The reason I am calling for a vote for these three styles is that when I am > proposing the style 2 to Gravitino, I got strong objection. > There are opinions leaning toward style 1, which I see as a bad practice. > > I want to hear from the community, but I don’t want to provoke a hot debate > across the community. > So please reply to this email with your preferred style: style 1, style 2, or > style 3. > > Thank you. > Qiming >
