Improve repository for newcomers#2380
Conversation
|
Could this all be a linting check performed by a Github Action? Surely this is something that could benefit all OCaml projects so people might be interested in adding this check to the CI of their projects. |
|
GitHub has https://github.com/ocaml-ppx/ocamlformat/community. I'm not sure what more can be done automatically. If someone is interested in building a linter for this, why not, but I see more value in focusing on the concrete changes (e.g. writing the roadmap isn't something that can be automated) |
Julow
left a comment
Julow
left a comment
There was a problem hiding this comment.
Nice! The contributing guide was not uptodate so there's a few corrections to do.
| 5. Remain engaged with the issue until closure as your feedback might be needed. | ||
|
|
||
| When acknowledged, the project maintainers will add [labels](#ocamlformat-labels) to your issue throughout its lifespan. | ||
| Once your issue is acknowledged, our maintainers will apply relevant [labels](#ocamlformat-labels) to track its status. |
There was a problem hiding this comment.
Talking about the labels seems unnecessary. Perhaps it can be removed to be straight to the point ? (same in pull requests)
There was a problem hiding this comment.
I've removed the mentions that maintainers use labels.
|
|
||
| - **Versioning:** Ocamlformat 1.1 should be backward compatible and allow users to format code as they did with 1.0 if the version is specified in the configuration file. | ||
| - **Customization:** Continue to support and add formatting options ocamlformat users care about. | ||
| - **Concrete Syntax:** We'll migrate ocamlformat from an AST to a CST that contains location information to improve the formatting of comments. |
There was a problem hiding this comment.
That's not the reason, the current AST contains locations and we are already capable of adding the missing locations to it.
The CST will make the code more robust to bugs by removing the need to guess the formatting of an abstract syntax that often have several possible syntaxes.
It could help with comments in an unspecified way, but that will not be related to locations.
|
|
||
| - **Versioning:** Ocamlformat 1.1 should be backward compatible and allow users to format code as they did with 1.0 if the version is specified in the configuration file. | ||
| - **Customization:** Continue to support and add formatting options ocamlformat users care about. | ||
| - **Concrete Syntax:** We'll migrate ocamlformat from an AST to a CST that contains location information to improve the formatting of comments. |
There was a problem hiding this comment.
| - **Concrete Syntax:** We'll migrate ocamlformat from an AST to a CST that contains location information to improve the formatting of comments. | |
| - **Concrete Syntax:** We'll migrate ocamlformat from an AST to a CST that contains more location information and preserve the original syntax. |
- Update the `test_branch` guidelines, which were outdated - Use dune directly - Remove mention of adding options and unclear mention of errors - Mention formatting
It is outdated and test_branch isn't expected to take arguments in the general case.
|
I applied all of my suggestion and rewrote partly the "Running the Tests" guidelines. It would be nice if you could review my changes. |
The ignore file in vendor/ do not seem to work as intended.
Julow
left a comment
Julow
left a comment
There was a problem hiding this comment.
No need to wait more, I'll merge once the CI is green.
| @@ -1 +0,0 @@ | |||
| vendor/** | |||
There was a problem hiding this comment.
This file seems necessary, I'll add it back. The new one in vendor do not seem to work.
|
The |
3 participants
Following on ocaml/odoc#962, this PR contains a few minor improvements and cosmetic changes to the repository to make it (hopefully) friendlier for newcomers.
Among the changes:
.opamfilesThe roadmap deserves special attention, let's be sure we agree on it before merging. Once its merged, I'll write a post on Discuss that links to it: users have been asking for clarity on the future of ocamlformat.