[jira](FLINK-31177) To introduce a formatter for Markdown files
As I mentioned in FLINK-31177 ( https://issues.apache.org/jira/browse/FLINK-31177): Currently, markdown files in *docs* are maintained and updated by many contributors, and different people have varying code style taste. By the way, as the syntax of markdown is not really strict, the styles tend to be inconsistent. To name a few, - Some prefer `*` to make a list item, while others may prefer `-`. - It is common to leave many unnecessary blank lines and spaces. - To make a divider, the number of `-` can be varying. To this end, I think it would be nicer to encourage or demand contributors to format their markdown files before making a pull request. Personally, I think Prettier (https://prettier.io/) is a good candidate. What do you think? -- Zhongpu Chen
[discussion] To introduce a formatter for Markdown files
As I mentioned in FLINK-31177 ( https://issues.apache.org/jira/browse/FLINK-31177): Currently, markdown files in *docs* are maintained and updated by many contributors, and different people have varying code style taste. By the way, as the syntax of markdown is not really strict, the styles tend to be inconsistent. To name a few, - Some prefer `*` to make a list item, while others may prefer `-`. - It is common to leave many unnecessary blank lines and spaces. - To make a divider, the number of `-` can be varying. To this end, I think it would be nicer to encourage or demand contributors to format their markdown files before making a pull request. Personally, I think Prettier (https://prettier.io/) is a good candidate. What do you think? -- Zhongpu Chen
RE: Re: [discussion] To introduce a formatter for Markdown files
> I was wondering how we could let every contributor follow the same mk rule. As long as contributors install Prettier with the same version, markdown files can be auto-formatted in the same way without extra working via the `prettier --write **/*.md` command, and this can also be set as a part of pre-commit hook. To check whether markdown files satisfy formatting requirements, we can use `prettier --check **/*.md` where exit code 0 means it does follow the styles. > Is there any way to integrate the format check into our CI pipeline? Yes, it is possible. I have tested using GitHub Actions, and I think Azure pipelines also support this feature. ```yml jobs: Check-MD-Format-Actions: runs-on: ubuntu-latest steps: - name: Check out repo code uses: actions/checkout@v3 - name: Prettify code uses: creyD/prettier_action@v4.2 with: prettier_options: --check **/*.md ``` > Another thing is that some docs are written with Hugo syntax. Would they work together with no conflict? Well, it will never cause any conflict. Since Hugo syntax is a superset of regular markdown syntax, and Prettier is compatible with CommonMark ( https://commonmark.org/) and GitHub Flavored Markdown. On 2023/02/22 10:22:46 Jing Ge wrote: > Hi Zhongpu, > > Thanks for starting this discussion. I was wondering how we could let every > contributor follow the same mk rule. I am not familiar with Prettier. Would > you like to help me understand some basic questions? Thanks. > > Is there any way to integrate the format check into our CI pipeline? > Otherwise, it will be hard to control it. Another thing is that some docs > are written with Hugo syntax [1]. Would they work together with no conflict? > > > Best regards, > Jing > > [1] https://gohugo.io/ > > On Wed, Feb 22, 2023 at 9:50 AM Zhongpu Chen wrote: > > > As I mentioned in FLINK-31177 ( > > https://issues.apache.org/jira/browse/FLINK-31177): > > > > Currently, markdown files in *docs* are maintained and updated by many > > contributors, and different people have varying code style taste. By the > > way, as the syntax of markdown is not really strict, the styles tend to be > > inconsistent. > > > > To name a few, > > > >- Some prefer `*` to make a list item, while others may prefer `-`. > >- It is common to leave many unnecessary blank lines and spaces. > >- To make a divider, the number of `-` can be varying. > > > > To this end, I think it would be nicer to encourage or demand contributors > > to format their markdown files before making a pull request. Personally, I > > think Prettier (https://prettier.io/) is a good candidate. > > What do you think? > > > > -- > > Zhongpu Chen > > >
RE: Re: [discussion] To introduce a formatter for Markdown files
Hi Jing, Sorry for the last reply in a messed up formatting, as I am not quite familiar with the mail list usage. First, as long as contributors install Prettier with the same version, markdown files can be auto-formatted in the same way without extra working via the `prettier --write **/*.md` command, and this can also be set as a part of pre-commit hook. To check whether markdown files satisfy formatting requirements, we can use `prettier --check **/*.md` where exit code 0 means it does follow the styles. Secondly, the format check can be integrated with the CI pipeline easily. Here is an example using GitHub Actions, and I think the setting in Azure pipelines is similar. ```yml jobs: Check-MD-Format-Actions: runs-on: ubuntu-latest steps: - name: Check out repo code uses: actions/checkout@v3 - name: Use Node.js uses: actions/setup-node@v3 with: node-version: "12.x" - name: Install pretty run: npm i -g prettier - name: Prettify code run: prettier --check **/*.md ``` At last, it will never cause any conflict. Prettier is compatible with CommonMark (https://commonmark.org/) and GitHub Flavored Markdown. On 2023/02/22 10:22:46 Jing Ge wrote: > Hi Zhongpu, > > Thanks for starting this discussion. I was wondering how we could let every > contributor follow the same mk rule. I am not familiar with Prettier. Would > you like to help me understand some basic questions? Thanks. > > Is there any way to integrate the format check into our CI pipeline? > Otherwise, it will be hard to control it. Another thing is that some docs > are written with Hugo syntax [1]. Would they work together with no conflict? > > > Best regards, > Jing > > [1] https://gohugo.io/ > > On Wed, Feb 22, 2023 at 9:50 AM Zhongpu Chen wrote: > > > As I mentioned in FLINK-31177 ( > > https://issues.apache.org/jira/browse/FLINK-31177): > > > > Currently, markdown files in *docs* are maintained and updated by many > > contributors, and different people have varying code style taste. By the > > way, as the syntax of markdown is not really strict, the styles tend to be > > inconsistent. > > > > To name a few, > > > >- Some prefer `*` to make a list item, while others may prefer `-`. > >- It is common to leave many unnecessary blank lines and spaces. > >- To make a divider, the number of `-` can be varying. > > > > To this end, I think it would be nicer to encourage or demand contributors > > to format their markdown files before making a pull request. Personally, I > > think Prettier (https://prettier.io/) is a good candidate. > > What do you think? > > > > -- > > Zhongpu Chen > > >
RE: Re: Re: [discussion] To introduce a formatter for Markdown files
Hi Jing,
Prettier is a versatile formatting tools with very limited options for
markdown files. If we need to specify the rules, I think other tools,
such as markdownlint [1], can be a better choice. As for markdownlint,
we can specify many kinds of rules. Here is an example for `unordered
list` whose style ID is MD004 [2].
```json
{ "default": true, "MD004": { "style": "asterisk" } }
```
Then markdown files only accept '*' for making a list item.
The specific formatting tools may be left as a vote later.
[1] https://github.com/DavidAnson/markdownlint
[2] https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
On 2023/02/22 21:22:02 Jing Ge wrote:
> Hi Zhongpu,
>
> Thanks for the clarification. Prettier looks fine for formatting mk
files.
> Is there any way to validate rules like e.g. only using '*' for listing
> items in the CI pipeline?
>
> Best regards,
> Jing
>
> On Wed, Feb 22, 2023 at 2:28 PM Zhongpu Chen wrote:
>
> > Hi Jing,
> >
> > Sorry for the last reply in a messed up formatting, as I am not quite
> > familiar with the mail list usage.
> >
> > First, as long as contributors install Prettier with the same version,
> > markdown files can be auto-formatted in the same way without extra
working
> > via the `prettier --write **/*.md` command, and this can also be
set as a
> > part of pre-commit hook. To check whether markdown files satisfy
formatting
> > requirements, we can use `prettier --check **/*.md` where exit code
0 means
> > it does follow the styles.
> >
> > Secondly, the format check can be integrated with the CI pipeline
easily.
> > Here is an example using GitHub Actions, and I think the setting in
Azure
> > pipelines is similar.
> >
> > ```yml
> > jobs:
> > Check-MD-Format-Actions:
> > runs-on: ubuntu-latest
> > steps:
> > - name: Check out repo code
> > uses: actions/checkout@v3
> > - name: Use Node.js
> > uses: actions/setup-node@v3
> > with:
> > node-version: "12.x"
> > - name: Install pretty
> > run: npm i -g prettier
> > - name: Prettify code
> > run: prettier --check **/*.md
> > ```
> >
> > At last, it will never cause any conflict. Prettier is compatible with
> > CommonMark (https://commonmark.org/) and GitHub Flavored Markdown.
> >
> >
> > On 2023/02/22 10:22:46 Jing Ge wrote:
> > > Hi Zhongpu,
> > >
> > > Thanks for starting this discussion. I was wondering how we could let
> > every
> > > contributor follow the same mk rule. I am not familiar with Prettier.
> > Would
> > > you like to help me understand some basic questions? Thanks.
> > >
> > > Is there any way to integrate the format check into our CI pipeline?
> > > Otherwise, it will be hard to control it. Another thing is that
some docs
> > > are written with Hugo syntax [1]. Would they work together with no
> > conflict?
> > >
> > >
> > > Best regards,
> > > Jing
> > >
> > > [1] https://gohugo.io/
> > >
> > > On Wed, Feb 22, 2023 at 9:50 AM Zhongpu Chen wrote:
> > >
> > > > As I mentioned in FLINK-31177 (
> > > > https://issues.apache.org/jira/browse/FLINK-31177):
> > > >
> > > > Currently, markdown files in *docs* are maintained and updated
by many
> > > > contributors, and different people have varying code style
taste. By
> > the
> > > > way, as the syntax of markdown is not really strict, the styles
tend to
> > be
> > > > inconsistent.
> > > >
> > > > To name a few,
> > > >
> > > > - Some prefer `*` to make a list item, while others may prefer `-`.
> > > > - It is common to leave many unnecessary blank lines and spaces.
> > > > - To make a divider, the number of `-` can be varying.
> > > >
> > > > To this end, I think it would be nicer to encourage or demand
> > contributors
> > > > to format their markdown files before making a pull request.
> > Personally, I
> > > > think Prettier (https://prettier.io/) is a good candidate.
> > > > What do you think?
> > > >
> > > > --
> > > > Zhongpu Chen
> > > >
> > >
> >
>
[DISCUSS] Why does the Doc say "Flink requires at least Java 11 to build"?
I reported the same question at StackOverflow [1]. As I tested in my computer, Java 8 is enough to build Flink from source. [1] https://stackoverflow.com/questions/75601233/ -- Zhongpu Chen
RE: [DISCUSS] Why does the Doc say "Flink requires at least Java 11 to build"?
Joachim Sauer[1] gave a good answer to my question. [1] https://stackoverflow.com/a/75604355/3741571 On 2023/03/01 13:21:33 Zhongpu Chen wrote: > I reported the same question at StackOverflow [1]. As I tested in my > computer, Java 8 is enough to build Flink from source. > > [1] https://stackoverflow.com/questions/75601233/ > > -- > Zhongpu Chen >
