From c1a4b7e48a5d29503d79e89f08b6e1a9ee26495b Mon Sep 17 00:00:00 2001 From: blazeu Date: Tue, 8 May 2018 20:50:05 +0700 Subject: [PATCH] Add MarkdownBear and format existing .md Closes https://github.com/coala/cEPs/issues/125 --- .coafile | 4 + README.md | 27 +++-- cEP-0000.md | 41 +++---- cEP-0001.md | 53 ++++---- cEP-0002.md | 86 ++++++------- cEP-0003.md | 44 +++---- cEP-0005.md | 123 ++++++++++--------- cEP-0006.md | 55 +++++---- cEP-0009.md | 42 ++++--- cEP-0010.md | 338 ++++++++++++++++++++++++++-------------------------- cEP-0012.md | 81 +++++++------ cEP-0013.md | 47 ++++---- cEP-0014.md | 307 ++++++++++++++++++++++++++++++++++------------- 13 files changed, 688 insertions(+), 560 deletions(-) diff --git a/.coafile b/.coafile index 38bb2ee0b..4b4541e3d 100644 --- a/.coafile +++ b/.coafile @@ -3,6 +3,10 @@ files = **.md use_spaces = yeah bears = SpaceConsistencyBear +[markdown] +files = **.md +bears = MarkdownBear + [commits] bears = GitCommitBear shortlog_regex = ([^:]*|[^:]+: [A-Z0-9*].*) diff --git a/README.md b/README.md index 4418f2d3a..30111fe3e 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,17 @@ This repository holds coala Enhancement Proposals. You can read more about them in the `cEP-0000.md` document. ## Index - | Filename | Title | Description | -|-----------------------|-------------------|-----------------------------------------------------| -| [cEP-0000](cEP-0000.md) | coala Enhancement Proposals | This cEP describes the official roles members of the coala community can hold and how they can vote on different levels of decisions.| -|[cEP-0001](cEP-0001.md) | Decision Making in coala | This cEP describes the official roles members of the coala community can hold and how they can vote on different levels of decisions. | -| [cEP-0002](cEP-0002.md) | Next Gen Bear Design | This cEP describes a new implementation of bears in coala which should make them simpler and make their design more intuitive and better. | -| [cEP-0003](cEP-0003.md) | Teams in coala|This is a proposal on how to decentralize the management of coala by introducing teams. | -| [cEP-0005](cEP-0005.md) | coala Configuration|One main pain point for our users is that coala is hard to configure. | -| [cEP-0006](cEP-0006.md) | coala Community Code of Conduct | Like the technical community as a whole, the coala team and community is made up of a mixture of professionals and volunteers from all over the world,working on every aspect of the mission - including mentorship, teaching, and connecting people. | -| [cEP-0009](cEP-0009.md) | Change status | This cEP proposes a mechanism to represent and extract information from project files and an interface to utilize the extracted information. | -| [cEP-0010](cEP-0010.md) |Convert bears to use aspects | This document describes how `aspects` will be defined for and connected with bears and how their results will be annotated with them. | -| [cEP-0012](cEP-0012.md) | coala's Command Line Interface|This cEP describes the design of coala's Command Line Interface (the action selection screen). | -| [cEP-0013](cEP-0013.md) | Cobot Enhancement and porting|This cEP describes about the new features that are to be added to cobot as a part of the [GSoC project](https://summerofcode.withgoogle.com/projects/#4913450777051136). | -| [cEP-0014](cEP-0014.md) | Generate relevant coafile sections | This cEP proposes a framework for coala-quickstart to generate more relevant `.coafile` sections based on project files and user preferences. | + +| Filename | Title | Description | +| ----------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cEP-0000](cEP-0000.md) | coala Enhancement Proposals | This cEP describes the official roles members of the coala community can hold and how they can vote on different levels of decisions. | +| [cEP-0001](cEP-0001.md) | Decision Making in coala | This cEP describes the official roles members of the coala community can hold and how they can vote on different levels of decisions. | +| [cEP-0002](cEP-0002.md) | Next Gen Bear Design | This cEP describes a new implementation of bears in coala which should make them simpler and make their design more intuitive and better. | +| [cEP-0003](cEP-0003.md) | Teams in coala | This is a proposal on how to decentralize the management of coala by introducing teams. | +| [cEP-0005](cEP-0005.md) | coala Configuration | One main pain point for our users is that coala is hard to configure. | +| [cEP-0006](cEP-0006.md) | coala Community Code of Conduct | Like the technical community as a whole, the coala team and community is made up of a mixture of professionals and volunteers from all over the world,working on every aspect of the mission - including mentorship, teaching, and connecting people. | +| [cEP-0009](cEP-0009.md) | Change status | This cEP proposes a mechanism to represent and extract information from project files and an interface to utilize the extracted information. | +| [cEP-0010](cEP-0010.md) | Convert bears to use aspects | This document describes how `aspects` will be defined for and connected with bears and how their results will be annotated with them. | +| [cEP-0012](cEP-0012.md) | coala's Command Line Interface | This cEP describes the design of coala's Command Line Interface (the action selection screen). | +| [cEP-0013](cEP-0013.md) | Cobot Enhancement and porting | This cEP describes about the new features that are to be added to cobot as a part of the [GSoC project](https://summerofcode.withgoogle.com/projects/#4913450777051136). | +| [cEP-0014](cEP-0014.md) | Generate relevant coafile sections | This cEP proposes a framework for coala-quickstart to generate more relevant `.coafile` sections based on project files and user preferences. | diff --git a/cEP-0000.md b/cEP-0000.md index 34a81c6f7..5216425b1 100644 --- a/cEP-0000.md +++ b/cEP-0000.md @@ -1,17 +1,15 @@ -coala Enhancement Proposals -=========================== +# coala Enhancement Proposals -|Metadata| | -|--------|-----------------------------------| -|cEP |0000 | -|Version |2.2 | -|Title |coala Enhancement Proposals | -|Authors |Lasse Schuirmann | -|Status |Active | -|Type |Process | +| Metadata | | +| -------- | ------------------------------------------ | +| cEP | 0000 | +| Version | 2.2 | +| Title | coala Enhancement Proposals | +| Authors | Lasse Schuirmann | +| Status | Active | +| Type | Process | -Abstract --------- +## Abstract This cEP describes the introduction of cEP's (coala Enhancement Proposals) to the coala community. @@ -23,8 +21,7 @@ features should not be implemented. They are obviously inspired by [PEP1](https://www.python.org/dev/peps/pep-0001/). -Spelling --------- +## Spelling As we all know, coala is written with a lower case c. The proper spelling of a cEP is `cEP-[0-9]{4}([a-z])?`, so `cEP-####` or `cEP-####x`. @@ -34,8 +31,7 @@ author wants to. Invalid ways to express cEP specifications include `CEP-####`, `cEP####`, `cep-####`, `Cep-####`, `CeP-####` and `CEp-####`. -Purpose -------- +## Purpose cEP's are in place so features in coala will be designed before implementation. Implementing major features usually happens from a technical perspective and @@ -45,8 +41,7 @@ oftentimes not well enough designed initially. This also makes sure, major features are properly documented. -Structure ---------- +## Structure Any cEP must at least hold the following information: @@ -55,8 +50,7 @@ Any cEP must at least hold the following information: Further chapters may be added as needed. -Metadata --------- +## Metadata The metadata table must hold the following items: @@ -73,8 +67,7 @@ The metadata table must hold the following items: (for code changes), `Active`, `Deprecated` or `Rejected`. - A **Type** which may be one of `Process` or `Feature`. -The Process ------------ +## The Process Any process changes may be initiated by level B decisions as described in cEP-1. @@ -122,11 +115,9 @@ A cEP may be rejected if the community determines. Follow up states are `Proposed`. -Patching cEP's --------------- +## Patching cEP's cEP's may be changed. If a cEP is changed, the version number has to be increased according to [semantic versioning](http://semver.org/). Patching a cEP to a higher version can be done with a B level decision. - diff --git a/cEP-0001.md b/cEP-0001.md index 346d9daad..8bae586f6 100644 --- a/cEP-0001.md +++ b/cEP-0001.md @@ -1,25 +1,20 @@ -Decision Making in coala -======================== +# Decision Making in coala -|Metadata| | -|--------|--------------------------------------------------------------------| -|cEP |0001 | -|Version |2.0 | -|Title |Decision Making in coala | -|Authors |Maximilian Scholz , Lasse Schuirmann , Mischa Krüger | -|Status |Active | -|Type |Process | +| Metadata | | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| cEP | 0001 | +| Version | 2.0 | +| Title | Decision Making in coala | +| Authors | Maximilian Scholz , Lasse Schuirmann , Mischa Krüger | +| Status | Active | +| Type | Process | - -Abstract --------- +## Abstract This cEP describes the official roles members of the coala community can hold and how they can vote on different levels of decisions. - -Roles ------ +## Roles The following roles can be held by members of the coala community: @@ -29,9 +24,9 @@ A newcomer is someone that was just introduced to the coala project and community and begins to contribute to it. This rank mainly represents the learning phase of the contribution process. -Every org member that started following the [newcomer guide](//coala.io/newcomer) -is declared a newcomer by invitation into the GitHub organisation. Newcomers can -work on issues with an assignment. +Every org member that started following the [newcomer +guide](//coala.io/newcomer) is declared a newcomer by invitation into the GitHub +organisation. Newcomers can work on issues with an assignment. ### Developer @@ -40,9 +35,9 @@ involved on a normal level and help with contributions and reviews on a semi-regular basis. When a newcomer finished the newcomer guide they can ask a maintainer to be -promoted to a developer. A developer has all the rights of a newcomer but can be an -official coala team member and can use cobot to label issues and pull requests. -Developers also have voting rights on A level decisions. +promoted to a developer. A developer has all the rights of a newcomer but can be +an official coala team member and can use cobot to label issues and pull +requests. Developers also have voting rights on A level decisions. If the contributions of a developer show the lack of fundamental understanding of the coala workflow they can be demoted to the newcomer rank with a B level @@ -56,9 +51,10 @@ A Maintainer is someone that showed persistence in contributions and or an increased quality compared to a developer. They offer experience and passion for the project and are granted full voting rights due to their achievements. -A developer can be promoted to a maintainer with a B level decision. This decision -does not have to be initiated by a maintainer so it is valid for a developer to -propose himself for a promotion. +A developer can be promoted to a maintainer with a B level decision. This +decision does not have to be initiated by a maintainer so it is valid for a +developer to propose himself for a promotion. + A maintainer has all the rights a developer has. Additionally maintainers have write access to coala repositories, can promote newcomers and developers and have voting rights on B and C level decisions. @@ -75,10 +71,9 @@ contributors to add their input to important decisions. The demotion from maintainer to developer represents a C level decision. It should only be done if a maintainer has shown inactivity for prolonged periods of time, half a year and upwards. -__This should not be used as a tool to silence unwanted opinions!__ +**This should not be used as a tool to silence unwanted opinions!** Maintainers may choose to be demoted to developers at any time. - ### Benevolent Limited Dictator (BLD) Members of the coala community have suggested the establishment of a Benevolent @@ -99,9 +94,7 @@ declares that person unwanted as a member of the coala community. This status stays active indefinitely but can be revoked at any point by a C level decision. - -Decision Types --------------- +## Decision Types ### A Level Decision diff --git a/cEP-0002.md b/cEP-0002.md index fd10bcabc..9dc7f3012 100644 --- a/cEP-0002.md +++ b/cEP-0002.md @@ -1,13 +1,13 @@ # Next Gen Bear Design -| Metadata | | -| ------------ |-----------------------------------------| -| cEP | 2 | -| Version | 1.1.3 | -| Title | Next gen bear design | -| Authors | Udayan Tandon | -| Status | Implementation Due | -| Type | Process | +| Metadata | | +| -------- | ---------------------------------------------- | +| cEP | 2 | +| Version | 1.1.3 | +| Title | Next gen bear design | +| Authors | Udayan Tandon | +| Status | Implementation Due | +| Type | Process | # Abstract @@ -39,35 +39,35 @@ utilising an extra thread. Here is the detailed implementation stepwise: 1. A `ProcessPoolExecutor` is created with the maximum number of processes -your CPU can run in parallel. + your CPU can run in parallel. 2. We proceed with getting an asynchronous event loop. This asynchronous event -loop creates `Concurrent.Futures` for tasks and schedules them to the process -pool. + loop creates `Concurrent.Futures` for tasks and schedules them to the process + pool. 3. Each task is given a callback when it has a result ready. This callback is -responsible for processing the result accordingly. + responsible for processing the result accordingly. 4. The `Bear` class will get two new methods. `execute_task()` and -`generate_tasks()`. - * The `generate_tasks()` is resposible for generating the correct - arguments for the upcoming tasks. - * The `execute_task()` method is scheduled by the event loop to the - process pool using the arguments from the `generate_tasks()` method. + `generate_tasks()`. + - The `generate_tasks()` is resposible for generating the correct + arguments for the upcoming tasks. + - The `execute_task()` method is scheduled by the event loop to the + process pool using the arguments from the `generate_tasks()` method. 5. Each bear will generate the following type of tasks: - * Global bears fire tasks that process all files. - * Local bears fire tasks for each individual file. + - Global bears fire tasks that process all files. + - Local bears fire tasks for each individual file. 6. A bear that has dependencies will only be scheduled to the process pool -once all its dependencies have been resolved. It's done in the following way: - * It's checked if the bear has some dependencies. - * If they haven't been resolved the bear is not scheduled. - * As soon as the dependencies are resolved for a bear it is removed from - the dependency dictionary and scheduled to the `ProcessPoolExecutor`. + once all its dependencies have been resolved. It's done in the following way: + - It's checked if the bear has some dependencies. + - If they haven't been resolved the bear is not scheduled. + - As soon as the dependencies are resolved for a bear it is removed from + the dependency dictionary and scheduled to the `ProcessPoolExecutor`. 7. A special purpose `Dependencies` class will be introduced to do the above -mentioned task. This will be responsible for keeping track of dependencies. -Whenever a bear completes it will be removed from the dependency class. + mentioned task. This will be responsible for keeping track of dependencies. + Whenever a bear completes it will be removed from the dependency class. 8. When all the tasks are done the event loop is stopped and closed. 9. You would not need to change any bears because coala will handle the -backwards compatibility. There will be new versions of `LocalBear` and -`GlobalBear` that will be called `FileWiseBear` and `ProjectWideBear` -respectively. + backwards compatibility. There will be new versions of `LocalBear` and + `GlobalBear` that will be called `FileWiseBear` and `ProjectWideBear` + respectively. # The File Proxy @@ -75,9 +75,9 @@ With the new bear design we are also moving to a new wrapper object to wrap every file. The file proxy is an object that contains properties about the file currently processed (such as the filename). It contains: -+ The filename, this is the starting point for every other attribute. -+ The content of the file as a string. -+ The content of the file, line-splitted. +- The filename, this is the starting point for every other attribute. +- The content of the file as a string. +- The content of the file, line-splitted. Note: Other properties can be included later as and when required. @@ -110,17 +110,17 @@ class FileProxy: A new class will be responsible for keeping track of the dependencies of each bear and it will work in the following manner: -+ The list of all the bears is passed to the class. -+ It takes this list and runs a method `check_circular_dependency` on it -to check if any bears in the list have circular dependencies. If they do -then we stop execution. -+ Each bear will add its dependencies to this tracker class. -+ Whenever a bear completes its execution the `resolve()` method of the -new class will be called with this bear as an argument. -+ This would mark this bear as complete in the dependency tracker. -+ Once the marking is complete the tracker returns all bears which have no -dependencies remaining as pending, so that their tasks can be scheduled to -the process pool. +- The list of all the bears is passed to the class. +- It takes this list and runs a method `check_circular_dependency` on it + to check if any bears in the list have circular dependencies. If they do + then we stop execution. +- Each bear will add its dependencies to this tracker class. +- Whenever a bear completes its execution the `resolve()` method of the + new class will be called with this bear as an argument. +- This would mark this bear as complete in the dependency tracker. +- Once the marking is complete the tracker returns all bears which have no + dependencies remaining as pending, so that their tasks can be scheduled to + the process pool. Here is a prototype: diff --git a/cEP-0003.md b/cEP-0003.md index 72a9a21d1..cdada247b 100644 --- a/cEP-0003.md +++ b/cEP-0003.md @@ -1,25 +1,20 @@ -Teams in coala -============== +# Teams in coala -|Metadata| | -|--------|-------------------------------------------------------------| -|cEP |0003 | -|Version |1.3 | -|Title |Teams in coala | -|Authors |Maximilian Scholz | -|Status |Active | -|Type |Process | +| Metadata | | +| -------- | ---------------------------------------- | +| cEP | 0003 | +| Version | 1.3 | +| Title | Teams in coala | +| Authors | Maximilian Scholz | +| Status | Active | +| Type | Process | - -Abstract --------- +## Abstract This is a proposal on how to decentralize the management of coala by introducing teams. - -Structure ---------- +## Structure A team is a self organizing group that is responsible for a certain aspect of coala. Code reviews should be done internally or in @@ -29,9 +24,7 @@ To support this self organization, issues in the coala scope shall have a label corresponding with one of the existing Teams. If a member finds an issue without such a label, a fitting one shall be set. - -Teams ------ +## Teams Teams are organized in the [coala/teams](https://github.com/coala/teams) repository. @@ -39,9 +32,7 @@ repository. A new team can be proposed explicit via an issue/pr or implicit via an application for a matching Team Leader. - -Roles ------ +## Roles A coala team consists of the following roles: @@ -58,7 +49,6 @@ company across all teams. Leaders may resign at any point. Reelections are held if the end of the term is further away than a month. - ### Team Member A Team Member agrees to focus their work on the aspect the teams is @@ -72,9 +62,7 @@ corresponding Team Leader and their acceptance represents a B Level Decision as proposed in cEP-0001 with the addition that one of the involved voters has to be the corresponding Team Leader. - -Electing Team Leaders ---------------------- +## Electing Team Leaders Any coala member may propose him or herself to be a Team Leader. The proposal should be public and include reasons and plans to take that @@ -91,9 +79,7 @@ and counted on 2016.12.24. The term starts after the evaluation of the votes is done. Dates are 00:00 GMT** - -Voting on Teams ---------------- +## Voting on Teams The decision to create a new Team represents a B Level Decision as specified in cEP-0001 and can be done any time. diff --git a/cEP-0005.md b/cEP-0005.md index b6782e20e..b7315caf0 100644 --- a/cEP-0005.md +++ b/cEP-0005.md @@ -1,14 +1,14 @@ # coala Configuration -| Metadata | | -| ------------ |--------------------------------------------------| -| cEP | 5 | -| Version | 2.2 | -| Title | coala Configuration | -| Authors | Lasse Schuirmann , | -| | Adhika Setya Pramudita | -| Status | Implementation Due | -| Type | Feature | +| Metadata | | +| -------- | ------------------------------------------------------- | +| cEP | 5 | +| Version | 2.2 | +| Title | coala Configuration | +| Authors | Lasse Schuirmann , | +| | Adhika Setya Pramudita | +| Status | Implementation Due | +| Type | Feature | ## Problem @@ -18,16 +18,15 @@ provide an abstraction over the tools by e.g. giving the same setting names to similar bears across languages so the user can reuse the same configuration for other languages too. -By integrating lots of different existing tools with coala we have gained a -huge set of possible analysis but it makes it very hard to understand and -configure without knowledge about a particular tool. Also the conflict of bears -versus linter bears that effectively offer multiple "checks" or sets of -analysis rises: it is confusing to have to use multiple bears for one language -for a set of analysis that is provided by only one bear for another language. +By integrating lots of different existing tools with coala we have gained a huge +set of possible analysis but it makes it very hard to understand and configure +without knowledge about a particular tool. Also the conflict of bears versus +linter bears that effectively offer multiple "checks" or sets of analysis rises: +it is confusing to have to use multiple bears for one language for a set of +analysis that is provided by only one bear for another language. -Other problems of the configuration file are, that some duplication is -involved, especially when dealing with settings that are used for file -collection. +Other problems of the configuration file are, that some duplication is involved, +especially when dealing with settings that are used for file collection. ## Proposal @@ -45,16 +44,16 @@ paragraph: - Explicit inheritance is possible by giving sections namespaces (`all.python` would inherit from the `all` section.) - Values can be added to inherited values. E.g. `ignore += ./vendor` would take - the inherited value and add `, ./vendor` to it. Note that additions within - a section will not be possible! The configuration should describe a state and + the inherited value and add `, ./vendor` to it. Note that additions within a + section will not be possible! The configuration should describe a state and not a program and must remain flow insensitive. - To specify, what analysis should be run the user will not have to care about bears. Instead, an `aspects` setting will be provided allowing the user to specify what `aspects` of their code should be analyzed. `aspects` could be - `Spelling` or `Smell` and are namespaced such that `Redundancy.Clone` will - be possible as well. `aspects` can be defined inclusive (analyze those aspects, - with the `aspects` settings) or exclusive (analyze all but those aspects, - with the `ignore_aspects` setting). + `Spelling` or `Smell` and are namespaced such that `Redundancy.Clone` will be + possible as well. `aspects` can be defined inclusive (analyze those aspects, + with the `aspects` settings) or exclusive (analyze all but those aspects, with + the `ignore_aspects` setting). - Specifying `bears` manually will still be possible as it eases use especially for bear developers. @@ -86,22 +85,21 @@ files = **.(c|h) ignore_aspects = Redundancy # Exclusive ``` -An aspect could be writen by its fully qualified name -(`Root.Redundancy.Clone`) or partially qualified name (`Redundancy.Clone` -or even `Clone`) and is case insensitive. Note that writing by partial name -could result in ambiguity. This could be resolved by writing the expanded -partially qualified name in such way to remove the ambiguity or just write -its fully qualified name. +An aspect could be writen by its fully qualified name (`Root.Redundancy.Clone`) +or partially qualified name (`Redundancy.Clone` or even `Clone`) and is case +insensitive. Note that writing by partial name could result in ambiguity. This +could be resolved by writing the expanded partially qualified name in such way +to remove the ambiguity or just write its fully qualified name. -In case of multiple aspects have the same taste name, ambiguity must be -resolved by prefixing the taste name with its aspect name. For example, -`max_length` is a taste of `Shortlog` and `LineLength`. Thus the `Shortlog` -would be defined like `Shortlog.max_length = 50`. +In case of multiple aspects have the same taste name, ambiguity must be resolved +by prefixing the taste name with its aspect name. For example, `max_length` is a +taste of `Shortlog` and `LineLength`. Thus the `Shortlog` would be defined like +`Shortlog.max_length = 50`. ### Bear API -Bears will receive the aspects that should be checked as a parameter and -results will get metadata to indicate what aspect has been checked. +Bears will receive the aspects that should be checked as a parameter and results +will get metadata to indicate what aspect has been checked. ```python from coalib.bears.LocalBear import LocalBear @@ -139,36 +137,37 @@ class RedundancyBear(LocalBear, aspects={ #### aspects -An aspect should just talk about a property of something, without qualifying -it. It should be named something like `Length` rather than `TooLong`. Then it -should be given the tastes. +An aspect should just talk about a property of something, without qualifying it. +It should be named something like `Length` rather than `TooLong`. Then it should +be given the tastes. For e.g. an aspect can be named as `Metadata.CommitMessage.Shortlog.Length` to represent the length property of the shortlog (first line) of a commit message. #### tastes -tastes are the values that are used to initialize the aspect settings. It -should not be something like `allow` or `check` which enables or disables an -aspect, rather it should be something more like a value which describes an -aspect in a specific, measurable way. It can be given as much context as -needed but not more. +tastes are the values that are used to initialize the aspect settings. It should +not be something like `allow` or `check` which enables or disables an aspect, +rather it should be something more like a value which describes an aspect in a +specific, measurable way. It can be given as much context as needed but not +more. For e.g. for the aspect `Metadata.CommitMessage.Shortlog.` -`FirstCharacterCasing`, set the taste `shortlog_starts_upper_case` as true if the -shortlog must begin with a upper case letter consistently, and false if the +`FirstCharacterCasing`, set the taste `shortlog_starts_upper_case` as true if +the shortlog must begin with a upper case letter consistently, and false if the opposite is true. -__Note:__ aspects and tastes are orthogonal concepts and should never overlap. -Therefore extreme caution must be taken while naming aspects and tastes to -avoid any discrepancy and inconsistency in the future. +**Note:** aspects and tastes are orthogonal concepts and should never overlap. +Therefore extreme caution must be taken while naming aspects and tastes to avoid +any discrepancy and inconsistency in the future. ### aspectclass The concept of aspects allows us to implement a consistency check and reduce documentation redundancy. Instead of documenting settings and results in every -bear, we can create a new aspects class. A working implementation of the -aspects concept is available [here](https://github.com/coala/coala/blob/cdaa239cc8e96e022f3b4e144e16a8a9303dcadd/coalib/bearlib/aspects/__init__.py). +bear, we can create a new aspects class. A working implementation of the aspects +concept is available +[here](https://github.com/coala/coala/blob/cdaa239cc8e96e022f3b4e144e16a8a9303dcadd/coalib/bearlib/aspects/__init__.py). An aspect can be defined as follows: @@ -264,20 +263,20 @@ class ColonExistence: This allows to show more information in results. Bears can give a custom result message; however, by default the message can be generated from the settings of -the aspects with the ``result_message`` function. +the aspects with the `result_message` function. -`aspects` can also define a ``style_paragraph`` function that returns a small +`aspects` can also define a `style_paragraph` function that returns a small paragraph describing how the user should write their source code according to -the given settings. This will be used to generate a full style definition from -a coala configuration. +the given settings. This will be used to generate a full style definition from a +coala configuration. Bears are expected to use all of the settings they get via the aspects. ## Implementation -The implementation will have to be two phased as we should ideally deprecate -the old way of using bears, keep it around for few releases and then phase it -out and remove unneeded source code. +The implementation will have to be two phased as we should ideally deprecate the +old way of using bears, keep it around for few releases and then phase it out +and remove unneeded source code. ### Gathering Metadata @@ -291,10 +290,10 @@ If multiple bears provide the same aspects, then coala will pick one of them with the following prioritization: 1. Could **fix** the problem, not only detect it. -2. Minimizing number of bears. For performance reason, it's faster to run - 1 bear that can handle 10 aspect rather than 10 bears for 10 aspect. -3. Run under the most common runtime. Rather than have 2 external bear - run with NodeJS and 2 with Ruby, try to get 4 that run under NodeJS. +2. Minimizing number of bears. For performance reason, it's faster to run 1 bear + that can handle 10 aspect rather than 10 bears for 10 aspect. +3. Run under the most common runtime. Rather than have 2 external bear run with + NodeJS and 2 with Ruby, try to get 4 that run under NodeJS. 4. Alphabetical order. coala will emit a log message that state the name and reason for each picked diff --git a/cEP-0006.md b/cEP-0006.md index b1e5a8dac..9599abbf6 100644 --- a/cEP-0006.md +++ b/cEP-0006.md @@ -1,17 +1,15 @@ -coala Community Code of Conduct -=============================== +# coala Community Code of Conduct -|Metadata| | -|--------|-----------------------------------| -|cEP |0006 | -|Version |1.0 | -|Title |coala Community Code of Conduct | -|Authors |Mariatta Wijaya | -|Status |Active | -|Type |Process | +| Metadata | | +| -------- | ------------------------------------------ | +| cEP | 0006 | +| Version | 1.0 | +| Title | coala Community Code of Conduct | +| Authors | Mariatta Wijaya | +| Status | Active | +| Type | Process | -coala Community Code of Conduct -------------------------------- +## coala Community Code of Conduct Like the technical community as a whole, the coala team and community is made up of a mixture of professionals and volunteers from all over the world, @@ -37,41 +35,41 @@ If you believe someone is violating the code of conduct, we ask that you report it by emailing `community AT coala DOT io`. -* **Be friendly and patient.** -* **Be welcoming.** We strive to be a community that welcomes and supports +- **Be friendly and patient.** +- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. -* **Be considerate.** Your work will be used by other people, and you in turn +- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language. -* **Be respectful**. Not all of us will agree all the time, but disagreement is +- **Be respectful**. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the coala community should be respectful when dealing with other members as well as with people outside the coala community. -* **Be careful in the words that you choose.** We are a community of +- **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: - * Violent threats or language directed against another person. - * Discriminatory jokes and language. - * Posting sexually explicit or violent material. - * Posting (or threatening to post) other people's personally identifying + - Violent threats or language directed against another person. + - Discriminatory jokes and language. + - Posting sexually explicit or violent material. + - Posting (or threatening to post) other people's personally identifying information ("doxxing"). - * Personal insults, especially those using racist or sexist terms. - * Unwelcome sexual attention. - * Advocating for, or encouraging, any of the above behavior. - * Repeated harassment of others. In general, if someone asks you to stop, - then stop. -* **When we disagree, try to understand why.** Disagreements, both social and + - Personal insults, especially those using racist or sexist terms. + - Unwelcome sexual attention. + - Advocating for, or encouraging, any of the above behavior. + - Repeated harassment of others. In general, if someone asks you to stop, + then stop. +- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and coala is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of coala comes from its varied community, @@ -81,7 +79,8 @@ coala DOT io`. to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes. -Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html). +Original text courtesy of the [Speak Up! +project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html). # Questions? diff --git a/cEP-0009.md b/cEP-0009.md index d81d0f6ec..f78a06e97 100644 --- a/cEP-0009.md +++ b/cEP-0009.md @@ -1,21 +1,26 @@ -| Metadata | | -| ------------ |----------------------------------------------------------| -| cEP | 9 | -| Version | 0.1 | -| Title | Extract and utilize information from project files | -| Authors | Satwik Kansal | -| Status | Active | -| Type | Feature | +| Metadata | | +| -------- | -------------------------------------------------- | +| cEP | 9 | +| Version | 0.1 | +| Title | Extract and utilize information from project files | +| Authors | Satwik Kansal | +| Status | Active | +| Type | Feature | ## Abstract -There are many kinds of project files like ".editorconfig", "Gruntfile.js", etc. that contain meta-information that can used by tools like coala-quickstart to provide better analysis. This cEP proposes a mechnaism to represent and extract information from project files and an interface to utilize the extracted information. +There are many kinds of project files like ".editorconfig", "Gruntfile.js", etc. +that contain meta-information that can used by tools like coala-quickstart to +provide better analysis. This cEP proposes a mechnaism to represent and extract +information from project files and an interface to utilize the extracted +information. ## Proposed Approach ### 1. Implementation of the “Info” class -A subclass of `Info` class will represent a specific kind of information. For example, the class `IgnorePathInfo` may represent “ignored file paths”. +A subclass of `Info` class will represent a specific kind of information. For +example, the class `IgnorePathInfo` may represent “ignored file paths”. ```py class Info: @@ -49,13 +54,14 @@ class Info: return self.__class__.__name__ ``` - ### 2. Implementation of “InfoExtractor” class Any derived class of the `InfoExtractor` abstract class consists of: + - Methods for parsing the project file. - Methods to find information in the parsed file. -- A collection of `Info` objects representing the information extracted from a particular kind of project file. +- A collection of `Info` objects representing the information extracted from a + particular kind of project file. - Files to parse and extract information from. ```py @@ -170,6 +176,7 @@ license_used = pjson_info.get("LicenseUsedInfo") ``` Another example + ```py class LinterUsedInfo(Info): description = "Linter used in project." @@ -201,9 +208,12 @@ coala_supported_linters = gfe.information.get("LinterUsedInfo") ## Possible Applications -This mechanism can be used by coala-quickstart to automatically extract some of the setting values for the bears and also to suggest project-relevant bears. +This mechanism can be used by coala-quickstart to automatically extract some of +the setting values for the bears and also to suggest project-relevant bears. Related Links: -- http://projects.coala.io/#/projects?project=enhance_coala-quickstart to extract information -- https://github.com/coala/coala-quickstart/issues/79 -- https://github.com/coala/coala-quickstart/issues/42 + +- to + extract information +- +- diff --git a/cEP-0010.md b/cEP-0010.md index 2cad84be6..028a501b9 100644 --- a/cEP-0010.md +++ b/cEP-0010.md @@ -1,13 +1,13 @@ # Convert bears to use aspects -| Metadata | | -| ------------ |------------------------------------------------| -| cEP | 10 | -| Version | 1.0 | -| Title | Convert bears to use aspects | -| Authors | Asnel Christian Ngoulla | -| Status | Implementation Due | -| Type | Feature | +| Metadata | | +| -------- | ----------------------------------------------------- | +| cEP | 10 | +| Version | 1.0 | +| Title | Convert bears to use aspects | +| Authors | Asnel Christian Ngoulla | +| Status | Implementation Due | +| Type | Feature | ## Abstract @@ -23,9 +23,9 @@ An `aspect` is an analysis we want to run over a piece of code. As stated in [cEP-0005](https://github.com/coala/cEPs/blob/master/cEP-0005.md), one of the main problems coala faces is its configuration due to the huge number of bears it offers, which are capable of analyzing several aspects of code and are -sometimes highly configurable with numerous settings; whereby the user has to -be aware of which bear does what and which setting has be to set to analyze -the aspect he wants analyzed; resulting in a coala difficult to learn and use. +sometimes highly configurable with numerous settings; whereby the user has to be +aware of which bear does what and which setting has be to set to analyze the +aspect he wants analyzed; resulting in a coala difficult to learn and use. To make things easier for user the concept of `aspects` was created as proposed in [cEP-0005](https://github.com/coala/cEPs/blob/master/cEP-0005.md). Our goal @@ -35,12 +35,10 @@ coala bears are capable of, annotating bears' results with them. ## The aspects The bears offered by coala are usually capable of handling several aspects. -`aspects` will be implemented in a tree-like form starting with the -[Root aspect](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/root.py). +`aspects` will be implemented in a tree-like form starting with the [Root +aspect](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/root.py). Here is the list of aspects to be implemented along with their corresponding -`subaspects` and tastes(which are the leaves of the tree written -in snake_case). - +`subaspects` and tastes(which are the leaves of the tree written in snake_case). ``` Root @@ -122,155 +120,161 @@ in snake_case). |--- Existence |--- Length |--- max_body_length - ``` -* `Root.Formatting`: This aspect checks on the format (the structure) of your -codebase. -* `Root.Formatting.UseSpaces`: This aspect enforces the use of spaces over -tabs. -* `Root.Formatting.TrailingSpace`: This aspect detects trailing spaces in the -code. -* `Root.Formatting.EmptyLines`: This aspect checks on empty lines. -* `Root.Formatting.EmptyLines.num_newlines_after_class_def`: -This taste represents the number of newlines that should be added after a class -definition. -* `Root.Formatting.EmptyLines.num_newlines_after_func_def`: -This taste represents the number of newlines that should be added after a -function definition. -* `Root.Formatting.Quotation`: This aspect checks on the quotations being used -in your files given `Root.Formatting.Quotation.prefered_quotation`. -* `Root.Formatting.Quotation.prefered_quotation`: This taste represents the -user's preferred quotation. -* `Root.Formatting.LineLength`: This aspect checks on lines' length in your -codebase. -* `Root.Formatting.LineLength.max_line_length`: This taste represents that -maximum length for line. -* `Root.Formatting.LineLength.Ignore`: This aspect represents all the -elements to be ignored. -* `Root.Formatting.LineLength.Ignore.ignore_links`: this taste is to determine -whether links should be ignored while checking on lines' length. -* `Root.Formatting.LineLength.Ignore.ignore_line`: this taste is to which line -should be ignored while checking on lines' length. -* `Root.Formatting.FileLength`: This aspect checks on files' length given -`Root.Formatting.FileLength.max_file_length`. -* `Root.Formatting.FileLength.max_file_length`: this taste represents the -maximum length for a file. -* `Root.Formatting.Indentation`: This taste checks on the number of space -used for indentation given `Root.Formatting.Indentation.size`. -* `Root.Smell`: This aspect describes `code smells` (smells refer to -structures that violate design principles) in your codebase. -* `Root.Smell.Complexity`: describes the complexity of your code given the -value `cyclomatic_complexity`. -* `Root.Smell.Complexity.cyclomatic_complexity`: Variable reprensing the -maximum number of embedded branches or embedded loops. -* `Root.Smell.ClassSmell`: This aslpect describes `code smells` related to -classes' definition in your codebase. -* `Root.Smell.ClassSmell.ClassLength`: This aspect deals with the length of -classes' definition. -* `Root.Smell.ClassSmell.ClassLength.max_class_length`: This taste represents -the maximum length for a class's definition. -* `Root.Smell.ClassSmell.ClassLength.min_class_length`: This taste represents -the minimum length for a class's definition. -* `Root.Smell.ClassSmell.FeatureEnvy`: This aspect describes classes that use -other classes' methods excessively. -* `Root.Smell.ClassSmell.DataClump`: This aspect describes variables -are passed around together in various parts of the program, suggesting -that they should pass as a single object. -* `Root.Smell.MethodSmell`: This aspect describes code smells -related to functions' (and or methods') definition. -* `Root.Smell.MethodSmell.max_method_length`: variable representing the -maximum length for a method or a function definition. -* `Root.Smell.MethodSmell.max_parameter`: This taste represents maximum number -of paramters for a function. -* `Root.Smell.Naming`: This aspect deals with identifiers' names(their -length, the naming convention in use ...) -* `Root.Smell.Naming.variable_naming_convention`: This taste represents the -naming convention used for variables' and functions' parameters' identifiers. -* `Root.Smell.Naming.function_naming_convention`: This taste -represents the naming convention used for functions' or methods'. -* `Root.Smell.Naming.class_naming_convention`: This taste represents the -naming convention being used for classes. -* `Root.Smell.Naming.max_identifier_length`: This taste represents the max -length for an identifier. -* `Root.Smell.Naming.min_identifier_length`: This taste represents the min -length for an identifier. -* `Root.Redundancy`: This aspect describes redundancy in your source code. -* `Root.Redundancy.Clone`: This aspect detects code -clones or more specifically very similar blocks of code in your codebase. -* `Root.Redundancy.Clone.min_clone_tokens`(a taste of the `Clone` aspect): -Thsi taste represents the minimun number of token that have to be equal to be -considered as a clone. -* `Root.Redundancy.UnusedImport`: This taste describes useless import/include -that is not needed. -* `Root.Redundancy.UnreachableCode`: This taste describes source code that -can never be executed during the program execution. -* `Root.Redundancy.UnusedFunction`: This taste describes functions that -are never called during code execution -* `Root.Redundancy.UnreachableStatement`: This taste describes statement that -are never executed during code execution. -* `Root.Redundancy.UnusedParameter`: This taste describes functions' -parameters which are never used. -* `Root.Redundancy.UnusedLocalVariable`: This taste describes variables which -are defined locally but never used. -* `Root.Redundancy.UnusedGlobalVariable`: this taste describes variables which -have a global scope but are never used. -* `Root.Spelling`: This aspect checks on the spelling of specific words. -* `Root.Spelling.coalaCorrect`: This aspect checks on the spelling of `coala`. -* `Root.Spelling.aspectsYEAH`: This aspect checks on the spelling of -`aspect[s]` and `aspectsYEAH`. -* `Root.UndefinedElement`: This aspect checks on undefined element in your -codebase. -* `Root.UndefinedElement.UndefinedVariable`: This aspect detects undefined -variables in your code. -* `Root.UndefinedElement.UndefinedParameter`: This aspect detects undefined -parameters in functions' definitions. -* `Root.UndefinedElement.UndefinedFunction`: This aspect detects undefined -functions in your codebase. -* `Root.Metadata`: This describes any aspect that is related to metadata that -is not inside your source code. -* `Root.Metadata.CommitMessage`. -* `Root.Metadata.CommitMessage.Emptiness`: This aspect is to detect and -prevent from using empty commit message. -* `Root.Metadata.CommitMessage.Shortlog`: This aspect checks on the first line -of your commit message. -* `Root.Metadata.CommitMessage.Shortlog.ColonExistence`: This aspect checks -your commit shortlog to see whether or not there is a colon (given that the -usage of colon is compulsory in your project). -* `Root.Metadata.CommitMessage.Shortlog.TrailingPeriod`: This aspect checks -for trailing period. -* `Root.Metadata.CommitMessage.Shortlog.Tense`: This aspect checks on the -tense used in commit message shortlog. -* `Root.Metadata.CommitMessage.Shortlog.Length`: This aspect checks on the -length of your commit message shortlog given the value of -`Root.Metadata.CommitMessage.Shortlog.Length.max_shortlog_length`. -* `Root.Metadata.CommitMessage.Shortlog.FirstCharacter`: This aspect detects -inconsistent casing for the first character of your commit message shortlog( -and the the first character following the colon if there is one) given the -value of -`Root.Metadata.CommitMessage.Shortlog.FirstCharacter.shortlog_starts_upper_case` -[taste representing the case to use for the first character of your -commit message shortlog and the first character following the colon]. -* `Root.Metadata.CommitMessage.Body`: Parent aspect for all of the aspects -related to your commit message body. -* `Root.Metadata.CommitMessage.Body.Existence`: Checks on the existence of -your commit message body (it enforces its usage). -* `Root.Metadata.CommitMessage.Body.Length`: Checks on the length of your -commit message body given the value of -`Root.Metadata.CommitMessage.Body.Length.max_body_length`. + +- `Root.Formatting`: This aspect checks on the format (the structure) of your + codebase. +- `Root.Formatting.UseSpaces`: This aspect enforces the use of spaces over tabs. +- `Root.Formatting.TrailingSpace`: This aspect detects trailing spaces in the + code. +- `Root.Formatting.EmptyLines`: This aspect checks on empty lines. +- `Root.Formatting.EmptyLines.num_newlines_after_class_def`: This taste + represents the number of newlines that should be added after a class + definition. +- `Root.Formatting.EmptyLines.num_newlines_after_func_def`: This taste + represents the number of newlines that should be added after a function + definition. +- `Root.Formatting.Quotation`: This aspect checks on the quotations being used + in your files given `Root.Formatting.Quotation.prefered_quotation`. +- `Root.Formatting.Quotation.prefered_quotation`: This taste represents the + user's preferred quotation. +- `Root.Formatting.LineLength`: This aspect checks on lines' length in your + codebase. +- `Root.Formatting.LineLength.max_line_length`: This taste represents that + maximum length for line. +- `Root.Formatting.LineLength.Ignore`: This aspect represents all the elements + to be ignored. +- `Root.Formatting.LineLength.Ignore.ignore_links`: this taste is to determine + whether links should be ignored while checking on lines' length. +- `Root.Formatting.LineLength.Ignore.ignore_line`: this taste is to which line + should be ignored while checking on lines' length. +- `Root.Formatting.FileLength`: This aspect checks on files' length given + `Root.Formatting.FileLength.max_file_length`. +- `Root.Formatting.FileLength.max_file_length`: this taste represents the + maximum length for a file. +- `Root.Formatting.Indentation`: This taste checks on the number of space used + for indentation given `Root.Formatting.Indentation.size`. +- `Root.Smell`: This aspect describes `code smells` (smells refer to structures + that violate design principles) in your codebase. +- `Root.Smell.Complexity`: describes the complexity of your code given the value + `cyclomatic_complexity`. +- `Root.Smell.Complexity.cyclomatic_complexity`: Variable reprensing the maximum + number of embedded branches or embedded loops. +- `Root.Smell.ClassSmell`: This aslpect describes `code smells` related to + classes' definition in your codebase. +- `Root.Smell.ClassSmell.ClassLength`: This aspect deals with the length of + classes' definition. +- `Root.Smell.ClassSmell.ClassLength.max_class_length`: This taste represents + the maximum length for a class's definition. +- `Root.Smell.ClassSmell.ClassLength.min_class_length`: This taste represents + the minimum length for a class's definition. +- `Root.Smell.ClassSmell.FeatureEnvy`: This aspect describes classes that use + other classes' methods excessively. +- `Root.Smell.ClassSmell.DataClump`: This aspect describes variables are passed + around together in various parts of the program, suggesting that they should + pass as a single object. +- `Root.Smell.MethodSmell`: This aspect describes code smells related to + functions' (and or methods') definition. +- `Root.Smell.MethodSmell.max_method_length`: variable representing the maximum + length for a method or a function definition. +- `Root.Smell.MethodSmell.max_parameter`: This taste represents maximum number + of paramters for a function. +- `Root.Smell.Naming`: This aspect deals with identifiers' names(their length, + the naming convention in use ...) +- `Root.Smell.Naming.variable_naming_convention`: This taste represents the + naming convention used for variables' and functions' parameters' identifiers. +- `Root.Smell.Naming.function_naming_convention`: This taste represents the + naming convention used for functions' or methods'. +- `Root.Smell.Naming.class_naming_convention`: This taste represents the naming + convention being used for classes. +- `Root.Smell.Naming.max_identifier_length`: This taste represents the max + length for an identifier. +- `Root.Smell.Naming.min_identifier_length`: This taste represents the min + length for an identifier. +- `Root.Redundancy`: This aspect describes redundancy in your source code. +- `Root.Redundancy.Clone`: This aspect detects code clones or more specifically + very similar blocks of code in your codebase. +- `Root.Redundancy.Clone.min_clone_tokens`(a taste of the `Clone` aspect): Thsi + taste represents the minimun number of token that have to be equal to be + considered as a clone. +- `Root.Redundancy.UnusedImport`: This taste describes useless import/include + that is not needed. +- `Root.Redundancy.UnreachableCode`: This taste describes source code that can + never be executed during the program execution. +- `Root.Redundancy.UnusedFunction`: This taste describes functions that are + never called during code execution +- `Root.Redundancy.UnreachableStatement`: This taste describes statement that + are never executed during code execution. +- `Root.Redundancy.UnusedParameter`: This taste describes functions' parameters + which are never used. +- `Root.Redundancy.UnusedLocalVariable`: This taste describes variables which + are defined locally but never used. +- `Root.Redundancy.UnusedGlobalVariable`: this taste describes variables which + have a global scope but are never used. +- `Root.Spelling`: This aspect checks on the spelling of specific words. +- `Root.Spelling.coalaCorrect`: This aspect checks on the spelling of `coala`. +- `Root.Spelling.aspectsYEAH`: This aspect checks on the spelling of `aspect[s]` + and `aspectsYEAH`. +- `Root.UndefinedElement`: This aspect checks on undefined element in your + codebase. +- `Root.UndefinedElement.UndefinedVariable`: This aspect detects undefined + variables in your code. +- `Root.UndefinedElement.UndefinedParameter`: This aspect detects undefined + parameters in functions' definitions. +- `Root.UndefinedElement.UndefinedFunction`: This aspect detects undefined + functions in your codebase. +- `Root.Metadata`: This describes any aspect that is related to metadata that is + not inside your source code. +- `Root.Metadata.CommitMessage`. +- `Root.Metadata.CommitMessage.Emptiness`: This aspect is to detect and prevent + from using empty commit message. +- `Root.Metadata.CommitMessage.Shortlog`: This aspect checks on the first line + of your commit message. +- `Root.Metadata.CommitMessage.Shortlog.ColonExistence`: This aspect checks your + commit shortlog to see whether or not there is a colon (given that the usage + of colon is compulsory in your project). +- `Root.Metadata.CommitMessage.Shortlog.TrailingPeriod`: This aspect checks for + trailing period. +- `Root.Metadata.CommitMessage.Shortlog.Tense`: This aspect checks on the tense + used in commit message shortlog. +- `Root.Metadata.CommitMessage.Shortlog.Length`: This aspect checks on the + length of your commit message shortlog given the value of + `Root.Metadata.CommitMessage.Shortlog.Length.max_shortlog_length`. +- `Root.Metadata.CommitMessage.Shortlog.FirstCharacter`: This aspect detects + inconsistent casing for the first character of your commit message + shortlog(and the the first character following the colon if there is one) + given the value of + + `Root.Metadata.CommitMessage.Shortlog.FirstCharacter.shortlog_starts_upper_case` + [taste representing the case to use for the first character of your commit + message shortlog and the first character following the colon]. +- `Root.Metadata.CommitMessage.Body`: Parent aspect for all of the aspects + related to your commit message body. +- `Root.Metadata.CommitMessage.Body.Existence`: Checks on the existence of your + commit message body (it enforces its usage). +- `Root.Metadata.CommitMessage.Body.Length`: Checks on the length of your commit + message body given the value of + `Root.Metadata.CommitMessage.Body.Length.max_body_length`. ## Implementation -As stated previously the aspects will be implemented in a tree like form, -with the Root aspect at the root of the tree. Some classes, metaclasses -and some few methods were define so far to make that possible including: +As stated previously the aspects will be implemented in a tree like form, with +the Root aspect at the root of the tree. Some classes, metaclasses and some few +methods were define so far to make that possible including: -* [the aspectbase class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/base.py) -* [the Documentation class for documenting aspects](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/docs.py) -* [the aspectclass metaclass](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/meta.py) -* [the TasteMeta class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/taste.py) -* [the Taste class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/taste.py) +- [the aspectbase + class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/base.py) +- [the Documentation class for documenting + aspects](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/docs.py) +- [the aspectclass + metaclass](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/meta.py) +- [the TasteMeta + class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/taste.py) +- [the Taste + class](https://github.com/coala/coala/blob/master/coalib/bearlib/aspects/taste.py) `aspects` will simply be defined this way: + ```python from coalib.bearlib.aspects import Root, Taste @@ -292,16 +296,17 @@ class SomeAspect: list('Possible value for this taste',), default='Default value for this taste') ``` -The documentation of each of the implemented aspects will be added to -the [coala/aspect-docs](https://github.com/coala/aspect-docs) repository. + +The documentation of each of the implemented aspects will be added to the +[coala/aspect-docs](https://github.com/coala/aspect-docs) repository. Concerning bears' results annotation, so far, the `.aspect` attr was added to -the [Result class](https://github.com/coala/coala/blob/master/coalib/results/Result.py) -(where a Result object is what is yielded by a bear when through executing). -So annotating a bear's result with aspects simply consists of setting this -variable to the appropriate aspect of code. -Here is how bears' will be defined in as presented in -[cEP-0005](https://github.com/coala/cEPs/blob/master/cEP-0005.md). +the [Result +class](https://github.com/coala/coala/blob/master/coalib/results/Result.py) +(where a Result object is what is yielded by a bear when through executing). So +annotating a bear's result with aspects simply consists of setting this variable +to the appropriate aspect of code. Here is how bears' will be defined in as +presented in [cEP-0005](https://github.com/coala/cEPs/blob/master/cEP-0005.md). ```python from coalib.bears.LocalBear import LocalBear @@ -334,4 +339,3 @@ class RedundancyBear(LocalBear, aspects={ # the aspect documentation! yield Result.from_values(aspect=aspect, ...) ``` - diff --git a/cEP-0012.md b/cEP-0012.md index 18e72e8f3..cb990dc92 100644 --- a/cEP-0012.md +++ b/cEP-0012.md @@ -1,25 +1,24 @@ -coala's Command Line Interface -============================== +# coala's Command Line Interface -|Metadata| | -|--------|--------------------------------------------------| -|cEP |0012 | -|Version |1.0 | -|Title |coala's Command Line Interface | -|Authors |Alexandru-Sorin Maxim | -|Status |Proposed | -|Type |Feature | +| Metadata | | +| -------- | --------------------------------------------------------- | +| cEP | 0012 | +| Version | 1.0 | +| Title | coala's Command Line Interface | +| Authors | Alexandru-Sorin Maxim | +| Status | Proposed | +| Type | Feature | +## Abstract -Abstract --------- +This cEP describes the design of coala's Command Line Interface (the action +selection screen). It intends to refactor the design released as part of coala +0.8. -This cEP describes the design of coala's Command Line Interface (the action selection screen). It intends to refactor the design released as part of coala 0.8. +Adds functionality alongside with a better interaction with the user. The final +goal is for coala CLI to be more friendly, easier to read and use. -Adds functionality alongside with a better interaction with the user. The final goal is for coala CLI to be more friendly, easier to read and use. - -Changes -------- +## Changes The following changes shall be made to the CLI: @@ -33,15 +32,14 @@ The following changes shall be made to the CLI: The section below describes why these changes should be done. -Why ---- +## Why ### Remove most of the text from the action selection screen Most of the people who use a CLI program do not read the whole output, only a small part of it. Also, a large output from a command could tire them and could -make them stop using our application. Remove the redundant information, -keeping only the necessary information. +make them stop using our application. Remove the redundant information, keeping +only the necessary information. ### Use letters instead of numbers for selecting actions @@ -50,31 +48,34 @@ Letters are easier to be remembered rather than numbers. (Do (n)othing). ### Allow chaining actions in a single input Users could apply more than one patch in a single input. The idea here is to -offer more flexibility to our users. Instead of just 1 number, the user could enter -more actions. +offer more flexibility to our users. Instead of just 1 number, the user could +enter more actions. ### Add a 'select action for all results' option -Now users have the possibility to choose at every result an action. -Adds the possibility to choose an action for all results. +Now users have the possibility to choose at every result an action. Adds the +possibility to choose an action for all results. ### Reprompt after running actions -This is an option that lets user choose whether they want another action after the current action is done. This way, users will have the flexibility in their hands. +This is an option that lets user choose whether they want another action after +the current action is done. This way, users will have the flexibility in their +hands. ### Set 'Do nothing' as the default action -If a user chooses a non-existent action (or the input is wrong) just exit from the program with 'Do nothing'. This is for reuse of 'Do nothing'. +If a user chooses a non-existent action (or the input is wrong) just exit from +the program with 'Do nothing'. This is for reuse of 'Do nothing'. The section below describes how we should make these changes. -How ---- +## How ### Remove most of the text from the action selection screen Most of the text that should be changed is in the 'ConsoleInteraction.py' file. -Make changes in the 'ConsoleInteraction.py' based on the feedback gathered with Google Form. +Make changes in the 'ConsoleInteraction.py' based on the feedback gathered with +Google Form. ### Use letters instead of numbers for selecting actions @@ -103,13 +104,15 @@ If a user will press 'C': [ ] Enter the letters of the patches you want to apply ('-' between any letter): a-i-n ``` -Any combination of letters (upper/lower) will be accepted (e.g: a-I-N). -If one of the actions requested isn't possible, a warning will be printed (after all possible actions are applied) with the letter that couldn't be satisfied. +Any combination of letters (upper/lower) will be accepted (e.g: a-I-N). If one +of the actions requested isn't possible, a warning will be printed (after all +possible actions are applied) with the letter that couldn't be satisfied. -1. Create a new file 'ChainAction.py' and a new class 'ChainAction' in 'result_actions' directory +1. Create a new file 'ChainAction.py' and a new class 'ChainAction' in + 'result_actions' directory 2. Implement the logic in the new class 3. Parse corectly the input -3. Use the new class in 'ConsoleInteraction' +4. Use the new class in 'ConsoleInteraction' ### Add a 'select action for all results' option @@ -136,9 +139,10 @@ If the user will press 'S': [ ] Choose an action: ``` -So, let's say that a user wants to add an ignore comment in all files. -The user should choose '(S)elect action for all results' and after choose the 'i' option. -This will add an ignore comment in all of the files used in coafile/command without asking another action. +So, let's say that a user wants to add an ignore comment in all files. The user +should choose '(S)elect action for all results' and after choose the 'i' option. +This will add an ignore comment in all of the files used in coafile/command +without asking another action. ### Reprompt after running actions @@ -149,7 +153,8 @@ This should work if the user chooses to (C)hain actions. [ ] Reprompt after running actions (Y/N)? ``` -If the user chooses 'Y', after all the actions are applied, the interface will be reprompted with the possible actions. +If the user chooses 'Y', after all the actions are applied, the interface will +be reprompted with the possible actions. ``` [ ] Do (N)othing diff --git a/cEP-0013.md b/cEP-0013.md index e1af3505a..050625385 100644 --- a/cEP-0013.md +++ b/cEP-0013.md @@ -1,31 +1,28 @@ -cobot Enhancement and porting -============================= +# cobot Enhancement and porting -|Metadata| | -|--------|---------------------------------------| -|cEP |13 | -|Version |1.0 | -|Title |cobot Enhancement and porting | -|Authors |Meet Mangukiya | -|Status |Proposed | -|Type |Process | +| Metadata | | +| -------- | ---------------------------------------------- | +| cEP | 13 | +| Version | 1.0 | +| Title | cobot Enhancement and porting | +| Authors | Meet Mangukiya | +| Status | Proposed | +| Type | Process | -Abstract --------- +## Abstract This cEP describes the details of the process of porting [cobot](https://gitlab.com/coala/cobot) from hubot(coffeescript framework) to [errbot](http://errbot.io)(python framework) and about the new features that are -to be added to cobot as a part of the -[GSoC project](https://summerofcode.withgoogle.com/projects/#4913450777051136). +to be added to cobot as a part of the [GSoC +project](https://summerofcode.withgoogle.com/projects/#4913450777051136). ## Why port? -coala community has grown substantially over last few months. To make it -easier on maintainers to cope up and still be a welcoming community for new -contributors, cobot is used. -Currently, cobot is a hubot instance, scripts for which are written -in Coffeescript. +coala community has grown substantially over last few months. To make it easier +on maintainers to cope up and still be a welcoming community for new +contributors, cobot is used. Currently, cobot is a hubot instance, scripts for +which are written in Coffeescript. coala is a python-inclined community, it makes sense to write the coala automation bot plugins in python. Writing the bot in python framework will @@ -37,6 +34,7 @@ cobot-hubot weren't written with tests. ## Why errbot? Errbot has many useful features: + 1. Internal support for webhooks. 2. pytest testing plugin. 3. Support for multiple backends. @@ -86,17 +84,16 @@ from webservices.coala.io/list/bears. See more at ``` - ### stats(bears, languages, contribution) Query the webservices at appropriate end point according to the stat requested. Endpoints: -1. `/list/bears` - for both bear and language stats. Language stats will be computed from the - languages key of the given object. -2. `/contrib` - for contribution stats. + +1. `/list/bears` for both bear and language stats. Language stats will be + computed from the languages key of the given object. +2. `/contrib` for contribution stats. + ``` > cobot contrib stats diff --git a/cEP-0014.md b/cEP-0014.md index 206df5530..a9e1db904 100644 --- a/cEP-0014.md +++ b/cEP-0014.md @@ -1,57 +1,82 @@ -Creating `.coafile` sections using quickstart -============================================= - -|Metadata| | -|--------|--------------------------------------------------| -|cEP |14 | -|Version |1.0 | -|Title |Creating `.coafile` sections using quickstart | -|Authors |Satwik Kansal | -|Status |Proposed | -|Type |Process | +# Creating `.coafile` sections using quickstart +| Metadata | | +| -------- | --------------------------------------------- | +| cEP | 14 | +| Version | 1.0 | +| Title | Creating `.coafile` sections using quickstart | +| Authors | Satwik Kansal | +| Status | Proposed | +| Type | Process | ## Abstract -This cEP proposes a framework for coala-quickstart to generate more relevant `.coafile` sections based on project files and user preferences. +This cEP proposes a framework for coala-quickstart to generate more relevant +`.coafile` sections based on project files and user preferences. ## Current flow of coala-quickstart -- Find all the files from the project directory, check `.gitignore` for files to ignore. -- Get the languages used in the project and their percentage from file extensions. -- Filter bears based on the languages used in the project and [curated sets](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py#L1) of important bears. -- Generate a `.coafile` by creating a section for each language, adding filtered bears corresponding to the language, and prompting the user for non-optional settings. +- Find all the files from the project directory, check `.gitignore` for files to + ignore. +- Get the languages used in the project and their percentage from file + extensions. +- Filter bears based on the languages used in the project and [curated + sets](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py#L1) + of important bears. +- Generate a `.coafile` by creating a section for each language, adding filtered + bears corresponding to the language, and prompting the user for non-optional + settings. ## Objectives -This first objective involves modifying the existing `filter_relevant_bears` method in the Bears module in coala-quickstart to select and filter bears based on: + +This first objective involves modifying the existing `filter_relevant_bears` +method in the Bears module in coala-quickstart to select and filter bears based +on: + - Languages detected in the project. - Linters already used by the project. -- The current `IMPORTANT_BEARS_LIST` in [`Constants.py`](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py) -- Information provided by users regarding the capabilities (`CAN_DETECT`, `CAN_FIX` labels) +- The current `IMPORTANT_BEARS_LIST` in + [`Constants.py`](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py) +- Information provided by users regarding the capabilities (`CAN_DETECT`, + `CAN_FIX` labels) - Installed bear dependencies -The second objective involves filling in the setting values for `.coafile` sections. - +The second objective involves filling in the setting values for `.coafile` +sections. ## Process ### Categorizing the files from which the information is extracted. -Based on the information they may provide, the target files of `InfoExtractor` classes can be categorized into following two categories: -1. Dependency files (Examples: `package.json`, `requirements.txt` and `Gemfile`) -2. Setting-values file (Examples: `.editorconfig`, `.gitignore` and `.csslintrc`) -Some files might belong both the categories (like `Gruntfile.js` and `Gulpfile.js`). +Based on the information they may provide, the target files of `InfoExtractor` +classes can be categorized into following two categories: + +1. Dependency files (Examples: `package.json`, `requirements.txt` and `Gemfile`) +2. Setting-values file (Examples: `.editorconfig`, `.gitignore` and + `.csslintrc`) -The dependency files can be used to prompt users to activate certain Bears if all the dependencies in Bear's `REQUIREMENT` field are present in the dependency files. -The setting-values files, on the other hand, are used to fill in the settings of the Bears and to detect conflicting configurations in the project. +Some files might belong both the categories (like `Gruntfile.js` and +`Gulpfile.js`). -Both categories of files, taken together, can complement each other to provide a scenario where "A dependency file finds BearA that can be activated, and the settings of BearA are derived by the information extracted from setting-values files" thereby automating the complete section generation process in some cases. +The dependency files can be used to prompt users to activate certain Bears if +all the dependencies in Bear's `REQUIREMENT` field are present in the dependency +files. The setting-values files, on the other hand, are used to fill in the +settings of the Bears and to detect conflicting configurations in the project. +Both categories of files, taken together, can complement each other to provide a +scenario where "A dependency file finds BearA that can be activated, and the +settings of BearA are derived by the information extracted from setting-values +files" thereby automating the complete section generation process in some cases. ### Collecting the meta-data -This section explains the meta-data that is required to be collected for filtering bears and generating sections. The data to be collected at runtime is as follows: + +This section explains the meta-data that is required to be collected for +filtering bears and generating sections. The data to be collected at runtime is +as follows: 1. Inverse Mappings of requirement types to the bears. + + ``` REQUIREMENTS_META = { “requirement_name” : { @@ -61,18 +86,28 @@ REQUIREMENTS_META = { } } ``` -This will be used to match against the `ProjectDependencyInfo` extracted from the project. In the case of a match, the corresponding bears may be suggested to the user. + +This will be used to match against the `ProjectDependencyInfo` extracted from +the project. In the case of a match, the corresponding bears may be suggested to +the user. 2. Mapping of language and the corresponding Bears available in coala-bears. + + ``` { "language_1": ["Bear1", "Bear2"], "language_2": ["Bear3", "Bear4"] } ``` -This will be generated at the runtime and will be used to filter bears based on languages used in the project. -3. Inverse Mappings of the `CAN_DETECT` and `CAN_FIX` capabilities metadata provided in the bears to the name of the bears. Example: +This will be generated at the runtime and will be used to filter bears based on +languages used in the project. + +3. Inverse Mappings of the `CAN_DETECT` and `CAN_FIX` capabilities metadata + provided in the bears to the name of the bears. Example: + + ``` CAPABILITIES_MAP = { “capability_name” : { @@ -83,31 +118,61 @@ CAPABILITIES_MAP = { }, } ``` -The users will be prompted to pick the desired capabilities in the beginning via the CLI, relevant bears are selected (with non-overlapping capabilities) and become part of the final generated `.coafile`. In future, these labels can be replaced or complemented by `DETECT_ASPECTS` and `FIX_ASPECTS` to enable users to provide their choices for "aspects" while selecting the bears. -4. Unified represenation of information extracted from `InfoExtractors` for project files like `.editorconfig`, `Gruntfile.js`, `package.json`, `.csslintrc`, etc (see this [issue](https://gitlab.com/coala/GSoC-2017/issues/21) and [cEP-0009](https://github.com/coala/cEPs/blob/master/cEP-0009.md) for more details) +The users will be prompted to pick the desired capabilities in the beginning via +the CLI, relevant bears are selected (with non-overlapping capabilities) and +become part of the final generated `.coafile`. In future, these labels can be +replaced or complemented by `DETECT_ASPECTS` and `FIX_ASPECTS` to enable users +to provide their choices for "aspects" while selecting the bears. + +4. Unified represenation of information extracted from `InfoExtractors` for + project files like `.editorconfig`, `Gruntfile.js`, `package.json`, + `.csslintrc`, etc (see this + [issue](https://gitlab.com/coala/GSoC-2017/issues/21) and + [cEP-0009](https://github.com/coala/cEPs/blob/master/cEP-0009.md) for more + details) + + ``` { "info_name": [InfoInstance1, InfoInstance2,] } ``` -The `Info` instances encapsulate the extracted information from project files. The various kinds of `Info` classes will be utilized on case-by-case basis. Example, `IgnorePathsInfo` may be used to exclude files from analysis right from the beginning, `ProjectDependencyInfo` might be used to match against the `REQUIREMENTS_META` discussed in point 1, `StyleInfo` may provide values to fill inside the generated `.coafile` sections. -5. Mechanism to extract all the non-optional settings of a Bear at the runtime. +The `Info` instances encapsulate the extracted information from project files. +The various kinds of `Info` classes will be utilized on case-by-case basis. +Example, `IgnorePathsInfo` may be used to exclude files from analysis right from +the beginning, `ProjectDependencyInfo` might be used to match against the +`REQUIREMENTS_META` discussed in point 1, `StyleInfo` may provide values to fill +inside the generated `.coafile` sections. +5. Mechanism to extract all the non-optional settings of a Bear at the runtime. ### Filtering and selecting bears from collected metadata -This section discusses the step-by-step procedure of selecting relevant bears and then creating `.coafile` sections from them. + +This section discusses the step-by-step procedure of selecting relevant bears +and then creating `.coafile` sections from them. 1. Identify all the languages used in the project. -2. Ask users to select capabilities based on possible `CAN_DETECT` and `CAN_FIX` label values. Store them in a list `desired_capabilities` like: +2. Ask users to select capabilities based on possible `CAN_DETECT` and `CAN_FIX` + label values. Store them in a list `desired_capabilities` like: + + ``` desired_capabilities = ["capability1", "capabilty2"] ``` -The "FIX" capabilites are stricter than "DETECT" capabilities. If a Bear has a capability to fix some aspect, it is obvious that it has capability to detect it. This fact will be taken into account while filtering bears by capabilities at a later step. The `desired_capabilities` list may also be pre-populated with some important capabilities (on similar lines as the existing [IMPORTANT_BEARS_LIST](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py#L1)) + +The "FIX" capabilites are stricter than "DETECT" capabilities. If a Bear has a +capability to fix some aspect, it is obvious that it has capability to detect +it. This fact will be taken into account while filtering bears by capabilities +at a later step. The `desired_capabilities` list may also be pre-populated with +some important capabilities (on similar lines as the existing +[IMPORTANT_BEARS_LIST](https://github.com/coala/coala-quickstart/blob/master/coala_quickstart/Constants.py#L1)) 3. Generate a dictionary named `candidate_bears` of the form + + ``` candidate_bears = { "detected_language_1": {"BearA", "BearB"}, @@ -115,48 +180,77 @@ candidate_bears = { "all": {"BearE", "BearF", "BearG"} } ``` -It is possible to have overlap among the lists in `candidate_bears` which will be resolved at later stage. + +It is possible to have overlap among the lists in `candidate_bears` which will +be resolved at later stage. 4. Initialize empty dictionary named `to_propose_bears`. 5. Initialize a dictionary named `selected_bears` to `IMPORTANT_BEARS_LIST`. -6. Given the metadata mentioned in the previous section is available, filter the `candidate_bears` lists as: - 1. Remove those bears from `candidate_bears` which do not contain any of the capability in `desired_capabilites` set. - 2. Among the remaining bears in `candidate_bears`, if some `ProjectDependenyInfo` extracted from the project matches the `REQUIREMENTS` field of bear (matching might also involve checking the compatibility of semvers), move the tuple `(Info, Bear)` to `to_propose_bears`. +6. Given the metadata mentioned in the previous section is available, filter the + `candidate_bears` lists as: + + 1. Remove those bears from `candidate_bears` which do not contain any of the + capability in `desired_capabilites` set. + 2. Among the remaining bears in `candidate_bears`, if some + `ProjectDependenyInfo` extracted from the project matches the + `REQUIREMENTS` field of bear (matching might also involve checking the + compatibility of semvers), move the tuple `(Info, Bear)` to + `to_propose_bears`. 7. For every bear in `to_propose_bears`: - 1. If there's enough extracted information from the project to fill in all the non-optional settings of the Bear, move the Bear to `selected_bears` list. - 2. Else, prompt the user on CLI with the evidence (the source of `Info` instance in the tuple) to enable the bear. If the user agrees, move the bear to `selected_bears`, otherwise discard the bear. -8. For each of the remaining bears in `candidate_bears`, eliminate bears having capabilities already satisfied in `selected_bears`. + 1. If there's enough extracted information from the project to fill in all + the non-optional settings of the Bear, move the Bear to `selected_bears` + list. + 2. Else, prompt the user on CLI with the evidence (the source of `Info` + instance in the tuple) to enable the bear. If the user agrees, move the + bear to `selected_bears`, otherwise discard the bear. + +8. For each of the remaining bears in `candidate_bears`, eliminate bears having + capabilities already satisfied in `selected_bears`. -9. Among the remaining bears in `candidate_bears`, in the case of conflicts in capabilities among the bears in the list: - 1. Eliminate bears having no unique capabilities among the other bears present in the list. - 2. Give preference to the bears already having dependencies installed (using the `check_prerequisites` field of the bears) and eliminate the respective conflicting bears. - 3. Add the remaining bears to `selected_bears` list. +9. Among the remaining bears in `candidate_bears`, in the case of conflicts in + capabilities among the bears in the list: + + 1. Eliminate bears having no unique capabilities among the other bears + present in the list. + 2. Give preference to the bears already having dependencies installed (using + the `check_prerequisites` field of the bears) and eliminate the + respective conflicting bears. + 3. Add the remaining bears to `selected_bears` list. 10. For every non-optional setting of each bear `selected_bears` object, + 1. If the setting's value exists in extracted information, do nothing. 2. Else, - 1. If the quickstart is being executed in interactive mode, prompt the user for the setting value. - 2. If non-interactive mode, discard the bear. - -11. Finally, create sections from the `selected_bears` list using the collected information values from user inputs and project files. + 1. If the quickstart is being executed in interactive mode, prompt the + user for the setting value. + 2. If non-interactive mode, discard the bear. -In future, more constraints can be added to further narrow down the list of selected bears by giving users more flexibility in terms of options like `max_bears`, `max_bears_per_language`, `exclude_languages`, etc. +11. Finally, create sections from the `selected_bears` list using the collected + information values from user inputs and project files. +In future, more constraints can be added to further narrow down the list of +selected bears by giving users more flexibility in terms of options like +`max_bears`, `max_bears_per_language`, `exclude_languages`, etc. ### Mapping extracted information to setting values. -To automatically fill in some of the setting values in `.coafile` sections, the `Info` classes need to be mapped to settings values of the Bears. These scope of applicability of these `Info` instances may vary from "bear-specific", to "section" to "global". -The scope for a mapping may be defined based on the: +To automatically fill in some of the setting values in `.coafile` sections, the +`Info` classes need to be mapped to settings values of the Bears. These scope of +applicability of these `Info` instances may vary from "bear-specific", to +"section" to "global". The scope for a mapping may be defined based on the: + - Source of the `Info` instance - Value of the `Info` instance - Class of the `Info` instance - Any other attribute encapsulated in the `Info` instance -The scope of the information can be represented by the `InfoScope` class as follows: +The scope of the information can be represented by the `InfoScope` class as +follows: + ```py class InfoScope: def __init__(self, @@ -220,11 +314,15 @@ class InfoScope: return False ``` -The ``InfoScope`` instances serve following two purposes while trying to fill an extracted information value to a setting based on mapping: +The `InfoScope` instances serve following two purposes while trying to fill an +extracted information value to a setting based on mapping: + 1. Check if the mapping if applicable for a given bear and a given section. -2. Check if the ``Info`` instance is valid based on its extraction source and the extractor class. +2. Check if the `Info` instance is valid based on its extraction source and + the extractor class. The mappings will be defined similar to the following way: + ```py INFO_SETTING_MAPS = { "setting_key_1": [ @@ -260,11 +358,14 @@ INFO_SETTING_MAPS = { } ``` -The mappings will be stored in a module named `InfoMappings.py` in coala-quickstart inside the `info_extraction` package. +The mappings will be stored in a module named `InfoMappings.py` in +coala-quickstart inside the `info_extraction` package. #### Filling-in the values of bear settings -An attempt to autofill the setting's value can be made before prompting the user to fill the values. This can be done as follows: +An attempt to autofill the setting's value can be made before prompting the user +to fill the values. This can be done as follows: + ```py def autofill_value_if_possible(self, setting_key, @@ -288,11 +389,17 @@ def autofill_value_if_possible(self, return None ``` - #### Detecting inconsistencies in project configurations -Another interesting application of the unified representation of extracted-information is detecting the inconsistencies among different project configurations. The intra-scope conflicts due to different Info from different sources can be brought up to users consideration. The inter-scope conflicts can be fixed either based on level-priority (global < section < bear) or by prompting users to select their preferred value. + +Another interesting application of the unified representation of +extracted-information is detecting the inconsistencies among different project +configurations. The intra-scope conflicts due to different Info from different +sources can be brought up to users consideration. The inter-scope conflicts can +be fixed either based on level-priority (global < section < bear) or by +prompting users to select their preferred value. The inconsistencies can be detected as + ```py to_fill_values = list(autofill_value_if_possible(some_setting, some_section, @@ -301,7 +408,10 @@ if len(to_fill_values) > 1: # warn the user about inconsistency. ``` -The inconsistencies need to be resolved before using the `Info` values to fill in the settings of `.coafile` sections. As a simple solution, user can be prompted like +The inconsistencies need to be resolved before using the `Info` values to fill +in the settings of `.coafile` sections. As a simple solution, user can be +prompted like + ``` > We found conflicting options in your file_a and your file_b, which should assume dominance? 1. file_a @@ -309,26 +419,38 @@ The inconsistencies need to be resolved before using the `Info` values to fill i 3. override both and specify your value ``` - ### Overall effect on coala-quickstart's CLI and outputs -After the bears are filtered, and relevant information has been extracted out of the projects, the users are notified, a more tailored version of coafile is written. -The per-language sections are generated like before, but with some additional bears included based on relevant information discovered from project and user's preference (CLI input). -The users are also prompted for the values like before, but an attempt is made to autofill these values before prompting the users. If there are multiple possible values to autofill, such inconsistencies are brought to user's consideration allowing him to pick any one or them or override all of them. + +After the bears are filtered, and relevant information has been extracted out of +the projects, the users are notified, a more tailored version of coafile is +written. The per-language sections are generated like before, but with some +additional bears included based on relevant information discovered from project +and user's preference (CLI input). The users are also prompted for the values +like before, but an attempt is made to autofill these values before prompting +the users. If there are multiple possible values to autofill, such +inconsistencies are brought to user's consideration allowing him to pick any one +or them or override all of them. #### Running mode options for quickstart - Robust mode (activate all the bears) - Non-interactive mode (choose the best `.coafile` without user interference) - + With default capabilities. (default option for non-interactive modes) - + Without any predefined capabilities. + - With default capabilities. (default option for non-interactive modes) + - Without any predefined capabilities. - Interactive mode (prompt for setting values) - + With user provided capabilities. (default option for interactive mode) - + With default capabilities. - + Without capabilities. + - With user provided capabilities. (default option for interactive mode) + - With default capabilities. + - Without capabilities. -There will be a `filter_by_capabilties` option which will be prompted to users in normal mode. In non-interactive mode, a command line flag `--no-default-capabilities` can be passed to disable filtering by default_capabilities. In case the `filter_by_capabilties` option is disabled, steps 8,9 and 10 in "Filtering and selecting bears from collected meta-data" section will be skipped. +There will be a `filter_by_capabilties` option which will be prompted to users +in normal mode. In non-interactive mode, a command line flag +`--no-default-capabilities` can be passed to disable filtering by +default_capabilities. In case the `filter_by_capabilties` option is disabled, +steps 8,9 and 10 in "Filtering and selecting bears from collected meta-data" +section will be skipped. A possible set of deault capabilties can be: + - Syntax - Formatting - Documentation @@ -341,25 +463,38 @@ A possible set of deault capabilties can be: 1. The user runs coala-quickstart and specifies project directories. 2. Languages are identified in the project. -2. All the ``InfoExtractor`` classes are instantiated, and the extracted information is aggregated and stored. -3. The user is asked if he wants to select bears based on capabilities. -4. The filtering and selection of bears take place as described in sections above. -5. After the bears are selected for every language present in the project, coala-quickstart tries automatically to fill the setting values for the bears, failing which, the user is prompted for the value. In case some inconsistency is encountered here, it is brought to user's consideration. -6. The per-language sections are generated, and final `.coafile` is written. +3. All the `InfoExtractor` classes are instantiated, and the extracted + information is aggregated and stored. +4. The user is asked if he wants to select bears based on capabilities. +5. The filtering and selection of bears take place as described in sections + above. +6. After the bears are selected for every language present in the project, + coala-quickstart tries automatically to fill the setting values for the + bears, failing which, the user is prompted for the value. In case some + inconsistency is encountered here, it is brought to user's consideration. +7. The per-language sections are generated, and final `.coafile` is written. ##### An example flow for the non-interactive mode 1. The user runs coala-quickstart and specifies project directories. 2. Languages are identified in the project. -3. All the ``InfoExtractor`` classes are instantiated, and the extracted information is aggregated and stored. -4. The filtering and selection of bears take place as described in sections above. -5. After the bears are selected for every language present in the project, coala-quickstart tries automatically to fill the setting values for the bears, failing which, the bear is discarded. In case some inconsistency is encountered here, an attempt is made to resolve it based on scope, failing which, the bear may be discarded, or any one of the possible value is filled in with a warning comment. +3. All the `InfoExtractor` classes are instantiated, and the extracted + information is aggregated and stored. +4. The filtering and selection of bears take place as described in sections + above. +5. After the bears are selected for every language present in the project, + coala-quickstart tries automatically to fill the setting values for the + bears, failing which, the bear is discarded. In case some inconsistency is + encountered here, an attempt is made to resolve it based on scope, failing + which, the bear may be discarded, or any one of the possible value is filled + in with a warning comment. 6. The per-language sections are generated, and final `.coafile` is written. - ## Code Samples ### Collecting extracted information from project + + ```py from coala_quickstart.info_extractors.GruntfileInfoExtractor import ( GruntfileInfoExtractor) @@ -410,6 +545,7 @@ def aggregate_info(infoextractors): ``` ### Collecting all the meta-data + ```py from collections import defaultdict @@ -511,8 +647,10 @@ def generate_requirements_map(bears): requirements_meta[req.package] = [to_add] return requirements_meta ``` + ### Filtering and selecting bears + ```py import copy @@ -734,6 +872,7 @@ def are_compatible_req_types(req_type_1, req_type_2): ``` ### Generating `.coafile` sections + ```py selected_bears = filter_relevant_bears( used_languages, desired_capabilities, extracted_info, arg_parser=None)