IMO we should have a small description somewhere in the tutorial, like we do with exit_codes

From @AbdealiJK on February 24, 2016 2:39

I notice that there are a few small things not there in Linter_Bears.rst like use_stderr ( @SanketDG didnt know about it :( )

Can we link the module documentation directly in RST files ? So they'd see the docstrings ?

Or do we again rewrite these types of documentations in Linter_bears.rst ? (I prefer just linking the API - it's really well documented ! ... although I wrote it, so i could be biased)

Copied from original issue: coala/coala#1686

From @underyx on June 3, 2016 19:35

area/documentation

Copied from original issue: coala/coala#2250

From @Makman2 on July 23, 2016 14:49

Here: https://github.com/coala-analyzer/coala/blob/master/coalib/bearlib/abstractions/Linter.py#L686

though this is the map currently supported:

severity_map=MappingProxyType({
                    "critical": RESULT_SEVERITY.MAJOR,
                    "c": RESULT_SEVERITY.MAJOR,
                    "fatal": RESULT_SEVERITY.MAJOR,
                    "fail": RESULT_SEVERITY.MAJOR,
                    "f": RESULT_SEVERITY.MAJOR,
                    "error": RESULT_SEVERITY.MAJOR,
                    "err": RESULT_SEVERITY.MAJOR,
                    "e": RESULT_SEVERITY.MAJOR,
                    "warning": RESULT_SEVERITY.NORMAL,
                    "warn": RESULT_SEVERITY.NORMAL,
                    "w": RESULT_SEVERITY.NORMAL,
                    "information": RESULT_SEVERITY.INFO,
                    "info": RESULT_SEVERITY.INFO,
                    "i": RESULT_SEVERITY.INFO,
                    "suggestion": RESULT_SEVERITY.INFO}),

Copied from original issue: coala/coala#2537

From @jschwarzwalder on June 12, 2016 20:20

The first action you direct the new user to try is to list all the bears that are supported by C.

This can be confusing and overwhelming for very first users.

Maybe you should walk them through running a bear that works for all languages on one specific file and then teach them how to find all the bears, or provide a link to a list of bears they can also try on their file.

Then you can direct them on what to expect when you just type in coala.

Copied from original issue: coala/coala#2326

sometimes

Hello
\~~~~~

World
-----

are both used. We should be consistent.

(Ignore the backslash above, GitHub has a rendering fault otherwise^^)

From @Uran198 on March 8, 2016 18:25

Only in some files there is use of function annotations.
It would be good to either use annotations everywhere or don't use them at all.

Copied from original issue: coala/coala#1848

From @Makman2 on June 3, 2016 23:53

On windows sometimes pip is screwed, we maybe should document the usage of python -m pip then.

Though I'm not sure, it's in fact a platform problem^^

Copied from original issue: coala/coala#2261

From @SanketDG on August 15, 2016 20:56

Copied from original issue: coala/coala#2614

From @hypothesist on June 11, 2016 11:29

After @sils1297 's PR is merged, it's --filter-by-language.

We can give space separated langauge names. We should also possibly introduce comma-separated.

Copied from original issue: coala/coala#2311

From @sils1297 on May 14, 2016 18:51

Copied from original issue: coala/coala#2145

http://blogory.org/add-content
Think we should add coala or something more generic even.

From @hypothesist on February 21, 2016 12:13

There is very little information currently on what they are.

Copied from original issue: coala/coala#1630

From @sils1297 on February 17, 2016 17:34

Update should cover:

• use of {filename} in the arguments string
• use of config file generation
• use of gives_correction

Copied from original issue: coala/coala#1557

we have some really cool flags and they can be mixed to do some really awesome stuff like coala -I -b <SOMEBEARNAME> -B gives the info about the given Bear, we should document this!

From @sils1297 on June 4, 2016 16:20

Copied from original issue: coala/coala#2276

From @Uran198 on April 13, 2016 16:19

From the discussion in #1875.
It should be documented that after the long discussion, should be created new issue with clearly defined task.

Copied from original issue: coala/coala#2010

From @Uran198 on March 26, 2016 20:49

Branched from coala/coala#1967

Is it a good idea to have such a large docstrings? Mostly, names are self descriptive and this huge kind of stuff can be added to documentations or references. Then, for some bears we can use **kwargs and just pass parameters as they are. Possibly, documenting each of them.

@sils1297 comment:

I personally really like that you can write all the documentation for the bear in the code and you don't have to think about where to write docs. And coala (i.e. we) takes care of organizing it properly for the user.

Copied from original issue: coala/coala#1968

From @Makman2 on March 26, 2016 20:6

Our current one sucks if you have more than brief single-line documentation (especiall see inside coala-bears JSHintBear).
I would go for this layout:

"""
Brief

Detailed

:param A:
    Description of A, indented by 4 spaces
:param super_extreme_long_so_documentation_would_look_bad:
    ...
"""

Opinions?

Copied from original issue: coala/coala#1967

From @AbdealiJK on March 6, 2016 5:56

coalang seems to be becoming more and more popular right now.
We have 2 issues blocked by it and it will probably become popular as we've depleted the list of linter based bears we want.

We should document it properly (once it actually stabilizes to some extent). I find lots of questions coming up about it in gitter.

@abhsag24 @hypothesist would love to know whether you think coalang is stable enough for this. If you think it's not, we should add the blocked label to this issue for now until its stable enough.

Copied from original issue: coala/coala#1816

After the sentence
First person should not be used here

From @Makman2 on May 17, 2016 19:22

Linter v2 API is there, should be used instead 👍

Copied from original issue: coala/coala#2160

From @Makman2 on June 2, 2016 23:21

Many people seem to struggle with the fact that there's no shell expansion any more, quotes and stuff are removed as they are special characters for grouping stuff.

We need to document that more properly I think^^

Copied from original issue: coala/coala#2226

From @jschwarzwalder on June 14, 2016 3:45

https://coala.readthedocs.io/en/latest/Users/Tutorials/Git_Help.html#squashing-your-commits

I"ve learned a few things in the past two days about where people can get stuck when trying to do a pull request.

1. DON"T HIT UPDATE
   If you get a message that your branch is out of date you need to follow these steps:
   Hi,

it looks like your PR is out of date and needs a rebase. This page may help you to get started on this. (Do not press the update branch button. It's evil.)

Add the original coala repository as a remote:

git remote add upstream https://github.com/coala-analyzer/coala.git
Then go to your branch and rebase it onto our master:

git checkout <yourbranch>
git fetch upstream
git rebase --interactive upstream/master

Now push it up. You will need to do a force push because you change history here (do not do this on master branches :)):

git push --force
Ping us on our gitter channel if you need help!

2. gitmate will check you line length and space at the end of your line
   Yeah you can't see it but its there, Its an easy fix, but where you can "git" into trouble is if you try to make a quick change and it makes a new commits.

See I was in the docs and I clicked on the friendly Edit on GitHub link in the upper corner. This as a bad idea, because I am not perfect and like the guide says it had errors the first time.

The trick is that you need to git commit -a --amend after you make a change, and its best to make the change locally

3. You will make a mistake and have multiple commits, but all is not lost

Count how many commits you have and then use this command to merge them into one
git rebase -i HEAD~9 where 9 is the number of commits you need to merge together

A screen will pop up, and the key is to type f or fixup next to all of the commits of the changes you made after your initial pull request.
More information about rebase
See this is important because gitmate checks each commit to see if it is passing. and if you make a new commit to fix the errors it found, it will always stop at the first commit. think of it like a while loop. While the first commit has error it will not move on to the next commit and check it. So you have to squash or fixup the change. This is essentially the same thing as typing git commit -a --amend,so in the future you should probably just do that.

Copied from original issue: coala/coala#2339

From @Makman2 on June 6, 2016 2:16

--> -S default_actions="*: ApplyPatchAction"

Copied from original issue: coala/coala#2303

Dash is a documentation searcher/browser app for macOS (it also has independent reimplementations for other platforms).

https://github.com/Kapeli/Dash-User-Contributions#contribute-a-new-docset

From @AbdealiJK on April 26, 2016 1:52

It would be nice to give a method of things to add if we want to crosstest things between coala and coala-bears as @Makman2 had to do for the Linter stuff.
Would be good to add to docs (so that if the branch which did this last time was deleted, it doesnt matter)

The last PR with crosstest is here: coala/coala-bears#314

Assigning Makman as he's the best one to do this I think

Copied from original issue: coala/coala#2074

From @sils1297 on June 2, 2016 18:6

@tltuan this might be something we could do together

Copied from original issue: coala/coala#2215

@Udayan12167 we need you to rewrite the section of the new deps on Writing_Bears page

From @Makman2 on May 20, 2015 18:35

The writing-bears guide should be improved. Some notes here and there, but the major aspect I have in mind:
A step-by-step guide that implements an actual bear of our coalib (in a simplified manner), so the user sees how to operate on files and do something meaningful. In my mind is the indentation bear, that should be fairly simple for one language (So we don't take the general LanguageDefinition feature in account or whatever).

One more idea:

• A little paragraph about global bears (as demonstration: A bear that calculates the MD5 hash - or any other hash-value - from all files)

Copied from original issue: coala/coala#561

From @hypothesist on March 5, 2016 7:29

Copied from original issue: coala/coala#1807

From @sils1297 on July 24, 2016 12:23

CC @Udayan12167 @Adrianzatreanu

Copied from original issue: coala/coala#2553

From @Makman2 on July 23, 2016 14:47

https://coala.readthedocs.io/en/latest/API/coalib.bearlib.abstractions.html#module-coalib.bearlib.abstractions.Linter

Copied from original issue: coala/coala#2536

From @Makman2 on February 24, 2016 0:2

I'm in favor of objective commit message writing :)

Copied from original issue: coala/coala#1684

Inside lines 26-28:

• the shortlog
• the commit body
• the issue reference

as without "the" readability is improved.

From @Uran198 on April 13, 2016 16:16

From the discussion in coala/coala#1875.
There should be an information in the contribution guide on what some labels imply, i. e.:

• if there is difficulty to the issue, then it is ready to be worked on.
• if there are no labels - it's pending review
• if there is a label status/needs design or status/needs info - there is still an ongoing discussion either on how to implement it, or should it be implemented.

Copied from original issue: coala/coala#2009

From @hypothesist on March 6, 2016 12:44

https://github.com/coala-analyzer/coala/blob/master/coalib/bearlib/languages/definitions/__init__.py is currently undocumented.

Copied from original issue: coala/coala#1824

From @AbdealiJK on April 23, 2016 14:16

readthedocs should have the google analytics id (can be found below). Need to check the docs of readthedocs and figure out how to do this, or just embed this html code into their code using RST.

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-76769778-2', 'auto');
  ga('send', 'pageview');

</script>

Copied from original issue: coala/coala#2040

From @Redridge on July 3, 2016 10:32

The docs are a bit vague about what and how should be done.
http://coala.readthedocs.io/en/latest/Users/Container.html#coala-on-gitlab-ci

Copied from original issue: coala/coala#2421

From @fneu on July 15, 2016 21:2

Basically we are already enforcing a style, where multiple-line lists, dicts, tuples, function definitions, function calls, and any such structures either:

• stay in one line
• span multiple lines that list one parameter/ item each

Since this is not covered by PEP8 we should add a section to our codestyle

Copied from original issue: coala/coala#2454

From @AbdealiJK on July 6, 2016 9:20

In the newcomers docs we should have an ascii cinema or Video tutorial on how to use git for our workflow.
Just makes it so much easier because people get confused about rebase -i and so on frequently.

I'm thinking 3 videos:

• How to make a contribution: (Clone, create branch, edit file, commit, push, possibly also add how to make a PR if it's not ascii cinema)
• How to modify my last commit / modify my commit message / modify my earlier (not last) commit
• How to rebase

Copied from original issue: coala/coala#2430

From @Makman2 on July 30, 2016 16:52

If someone needs the API, he/she looks for the word "API". Also "(generated)" does not really help ^^

Copied from original issue: coala/coala#2575

I don't know how the API was getting generated in coala, but we should do it here too.

Actually maybe even not, as we want to do a nice API documentation anyway, so if anyone feels like doing it, we'd love it!

From @AbdealiJK on June 23, 2016 4:6

I was submitting a patch at scikit-image and I was really impressed with their default PR message:

## Description
[Tell us about your new feature, improvement, or fix! If relevant, please supplement the PR with images.]


## Checklist
[It's fine to submit PRs which are a work in progress! But before they are merged, all PRs should provide:]
- [ ] Clean style in [the spirit of PEP8](https://www.python.org/dev/peps/pep-0008/)
- [ ] [Docstrings for all functions](https://github.com/numpy/numpy/blob/master/doc/example.py)
- [ ] Gallery example in `./doc/examples` (new features only)
- [ ] Unit tests

[For detailed information on these and other aspects see [scikit-image contribution guidelines](http://scikit-image.org/docs/dev/contribute.html)]


## References
[If this is a bug-fix or enhancement, it closes issue # ]
[If this is a new feature, it implements the following paper: ]

The checklist is really nice and serves as a better reminder of "things to do" as compared to writing it in a documentation.

Copied from original issue: coala/coala#2389

From @RohanVB on July 24, 2016 11:1

The current command prompt is displayed as :

To see what coala can do for your language, run:

$ coala --show-bears --filter-by-language Python

Since we are giving an example, the statement above the command prompt should be specific to Python.

Copied from original issue: coala/coala#2551

From @Redridge on February 15, 2016 11:40

In order for the docs to be correct, the code that the docs contain must be correct.
For that matter the docs should be all doctest stable. doctest
Rewrite/Imporve the docs such that they use doctest

difficulty/low

Copied from original issue: coala/coala#1498

From @underyx on July 14, 2016 13:18

After coala/coala#2450 is closed there should be a default directory inside project directories where custom bears can be added. This feature is really useful, but hard to come across right now.

area/documentation

Copied from original issue: coala/coala#2451

From @AbdealiJK on February 23, 2016 6:6

Currently import coalib followed by help(coalib) is not very useful. It just gives a list of packages inside. We should ideally have a description of coala/coalib there too.

I think we need to add a doc-comment in coalib.init.py which gives better information.

We could also use this in the setup.py maybe ?

Copied from original issue: coala/coala#1663

From @Adrianzatreanu on August 17, 2016 12:52

We need a way better API documentation, such as Python API docs are.

Copied from original issue: coala/coala#2635