diff --git a/_projects/standardised-file-format.md b/_projects/standardised-file-format.md new file mode 100644 index 00000000..5eaa327a --- /dev/null +++ b/_projects/standardised-file-format.md @@ -0,0 +1,76 @@ +collaborating_projects: + - coala +desc: "Provide support to a standardised file format(TOML) for writing + configurations" +difficulty: hard +initiatives: + - GSoC +markdown: standardised-file-format.md +mentors: + - Nosferatul + - RaiVaibhav +name: "Support TOML for writing configurations" +requirements: + - "The applicant should have at least one patch merged to + coala" + - "The applicant should be familiar with Python." + - "The applicant should be familiar with coala configuration system" +tags: + - Core + - Configuration + - TOML +--- + +This project aims to support a standardised file format like TOML for writing +settings. +Currently coala has a INI style config. It has `LineParser` and `ConfParser` +classes to parse the settings into sections. These sections are later executed +by running the appropriate bear. coala also a `ConfWriter` class to write +sections back into settings file like `.coafile` + +This approach has certain limitations. Custom sub-level parsing in +INI style config is tough and error prone. It makes `LineParser` and +`ConfParser` more complex and bug prone and also would slow down the speed of +development. A solution would be to use standardised file format like TOML. +Using `toml.load` on the config file will return a dictionary. This makes +custom sub-level parsing not only easy and accurate but also less error prone. +Also more importantly completely removes the need for `LineParser`. + +TOML provides flexibility, consistency, backwards compatibility and standard. +It has widespread acceptance, documentation and robust parsers. TOML has been +recommended as the configuration file for software packages to specify their +build dependencies. Due to its popularity it offers a reduced learning curve +compared to INI style config. + +#### Milestones + +##### PREPARATION/BONDING + +- The applicant has created and merged a cEP for this project. +- The applicant should be familiar with the codebase. +- The applicant should know how to work with the community. +- The mappings between `.coafile` to `TOML` must be finalised + +##### CODING PHASE 1 + +- Create a class named `TomlConfParser` to load settings from TOML + file into sections. +- The corresponding code is properly tested, documented, reviewed, + and merged. +- Write and test all possible settings in the new parser. + +##### CODING PHASE 2 + +- Create a class named `TomlConfWriter` to write sections into + TOML file. +- The corresponding code is properly tested, documented, reviewed, + and merged. +- Test all possible settings in the new writer. + +##### CODING PHASE 3 + +- Support required and missing features in the parser by making PR's to + [toml](https://github.com/uiri/toml) +- Create a tool which converts existing .coafile into TOML config file. +- New coala tutorials and user guides have been created to show how to + write settings in TOML.