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
