Investigate the formatting tool for the project

[llxia]

It is very important to have a good coding standard. It helps to keep the code simple and clean. A nice formatted code is easier for people to understand, review, compare, maintain and update. We should investigate a good formatting tool for the project. Below are some of the requirements:

• easy to use
• integrates well with different IDEs
• support multiple languages (js, JSON, CSS, etc)

Possible tool: https://prettier.io/

Addtional description (see https://github.com/adoptium/aqa-test-tools/issues/591#issuecomment-1023239334)

[yinggzz]

I'd love to investigate on the tool

[yinggzz]

Here are some potential formatting tools for the project I have found.

Prettier:

• Supports: JavaScript, Flow, TypeScript, CSS, SCSS, Less, JSX, GraphQL, JSON, Markdown with plugins you can use it for Python, PHP, Swift, Ruby, Java and more
• Integrates with most editors: VS Code, Sublime Text, Atom, Espresso, Visual Studio, WebStorm, formatter applied every time change is saved
• Enforces proper consistent styling of the codebase across the entire codebase: maintainability of large-size code

CodeBeautify

• Used by companies like Facebook, Spotify, Discord, PayPal…
• Supports conversion between Json, HTML, XML, YAML to other languages.
• Supports beautifying tools for JSON, CSS, XML, Java, etc.
• Methods: File upload, URL, coy and paste
• Chrome extension version exists

RubyMine

• Support for Ruby and Rails, JavaScript, CoffeeScript, ERB, HAML, CSS, SaSS and LESS, and more
• Supports code formatting and code completion
• Helps maintain required code style
  • Able to configure code style settings for every language in a project.

Language Specific Java:

• Java code formatter in IntelliJ: eClint https://github.com/jedmao/eclint - configured using .editorconfig file

Python: Black

• Uses the black code style
• Can be installed by pip install black - unix style command line tool
• Able to read project-specific default values for its command line options from a pyproject.toml file

[smlambert]

Thanks @yinggzz ! Based on our discussion today, you and @llxia have a few additional activities on this one, focussing on Prettier and CodeBeautify. Think about what we would expect of contributors to this repository. Would we 'enforce' formatting with a PR check? Are their github actions that would allow for this as part of a workflow? If we do not enforce it, is this mainly about creating a template and document guidelines?

[llxia]

The goal is this task is to find a formatting tool that can format automatically for the users. Ideally, the PR should be formatted well before users submit the PRs. I would expect that there is no or minimal work for both users and reviewers for formatting.

• CodeBeautify is not what we are looking for. It is a third-party online tool that users have to manually format their files on its site.

• Using Prettier as an example, we can check in our formatter file in the repo. And users can just install Prettier for their IDE (i.e., Formatter for Visual Studio Code https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode). Once it is installed and configured (one-time setup), the files will be auto-formatted at saving. Or a husky hook can be added to prettify on commit https://prettier.io/docs/en/precommit.html

PR checks may be needed for users that do not use common IDE with formatter tool support. This can be discussed at a later stage. But for this issue, I would like to focus on:

• investigate if there are any other tools (except Prettier) - I have a personal preference for Prettier, but I am open to other suggestions.
• identify 2~3 top ones and try them out. List Pros vs Cons.
• choose one to use in the project and identify the workflow
• define default formater file and check in the repo
• update the documentation with details

Thanks @yinggzz for your work so far. I hope the above description clarifies the goal and scope of this task. If you have any questions, please let us know.

[yinggzz]

Hi @llxia , thank you for your instruction! After a lot of research, I couldn’t really find other tools that are similar to Prettier and support integration with different IDEs and languages.

Please see below for my research on Prettier, it can be used as a pre-commit tool to format file before committing.

I was wondering if you can elaborate what to include in the “Format file” besides links for downloading it for different code editors.

[yinggzz]

Prettier Pros:

• as contributors for open sources are dispersed or new to the project, with Prettier, individuals not familiar with the style guidelines don’t have to worry when making a pull request
• owners, maintainers, collaborators don’t have to enforce a style guide in code reviews
• consistent code formatting across entire codebase
• Installing and using Prettier in a project is generally a straightforward process, and Prettier’s documentation is exemplary.

Cons:

• some styling/markup/programming languages not supported, for a list of languages it supports, see: https://prettier.io/docs/en/

Pull-requests, pre-commit hook

• Each contributor to the project can write own styled code, Prettier will format it before anyone code review it. When changes are committed, files in the commit will automatically be formatted.
• You can use Prettier with a pre-commit tool. This can re-format your files that are marked as “staged” via git add before you commit.
• There are many options to achieve this: https://prettier.io/docs/en/precommit.html
• Prettier pre-commit hook set-up: https://sia.codes/posts/how-to-add-prettier-to-a-project/

Example use case for a project: Run prettier on a large code base at once https://flexport.engineering/upgrading-prettier-on-a-large-codebase-28d56c4de49e

Goal: run prettier so that changes it makes are attributed correctly in git, no merge conflict in open pull requests, repeatable.

1. develop a small set of scripts to install and upgrade prettier
2. run it on every file in code base, clean up errors, make commit to master and update all open pull request *scripts should be run without anyone else committing to master before the scripts finish.

General work flow to automate code formatting in pull requests: https://peterevans.dev/posts/github-actions-how-to-automate-code-formatting-in-pull-requests/

1. When a pull request is raised the workflow executes as a check.
2. The code formatter executes and modifies files if necessary.
3. The workflow checks to see if any tracked files by git have been modified.
4. If modified files exist they are committed and pushed to the remote.
5. When using a repo scoped Personal Access Token instead of GITHUB_TOKEN, the push triggers all pull request checks to run again.

[llxia]

Add prettier in TRSS https://github.com/adoptium/aqa-test-tools/pull/611

[llxia]

https://github.com/adoptium/aqa-test-tools/pull/612 https://github.com/adoptium/aqa-test-tools/pull/613

[llxia]

Code formatter prettier is added in TRSS. I will close this issue.