Skip to content
Permalink
Browse files

CONTRIBUTING: typos, broken links and wording

Change-Id: I87e8f586367989682867f2b440c5be6ca4b6c1b5
  • Loading branch information
smokey42 committed Nov 5, 2019
1 parent 4267985 commit 7fa2fc35a7cd3b5f5c5e2fc4623e091cf75515fe
Showing with 24 additions and 24 deletions.
  1. +23 −23 CONTRIBUTING.md
  2. +1 −1 README.md
@@ -2,7 +2,7 @@

We welcome contributions to [Checkmk on Github](https://github.com/tribe29/checkmk).

Most contributions to Checkmk are small bugfixes, enhancements of existing
Most contributions to Checkmk are small bug-fixes, enhancements of existing
features, or completely new plugins. The guidelines below address these types
of contributions.

@@ -113,7 +113,7 @@ Now start developing and create one or multiple commits.
**Important**: Do one thing in one commit, e.g. don't mix code reorganization and
changes of the moved lines. Separate this in two commits.

Make sure that you commit in logical blocks and write [good commit messages](#commit-messages).
Make sure that you commit in logical blocks and write [good commit messages](#style-guide-commit-messages).

If you have finished your work, it's a good time to [execute the tests locally](#how-to-execute-tests)
to ensure you did not break anything.
@@ -207,19 +207,19 @@ don't need to execute the formatting test at all.
You could also push your changed to your forked repository and wait for Travis
to execute the tests for you, but that takes several minutes for each try.

## Styleguide: Guidelines for coding check plug-ins
## Style guide: Guidelines for coding check plug-ins

Respect the [Guidelines for coding check plug-ins](https://checkmk.com/cms_dev_guidelines.html).

## Styleguide: Commit messages
## Style guide: Commit messages

- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- The first line is a short title (limit to 72 characters or less)
- Reference issues and pull requests liberally after the first line
- Write [good commit messages](https://chris.beams.io/posts/git-commit/)

## Styleguide: Python
## Style guide: Python

The guidelines listed here are binding for the development at Checkmk in
Python.
@@ -241,7 +241,7 @@ the language to use.
Only rely on non-standard modules that are mentioned in the `Pipfile`.
<!--- TODO: How to add new modules? -->

### Agent plugins: Supported python versions
### Agent plugins: Supported Python versions

The agent plugins need to be executed on older Linux systems which may
have very old Python versions available. For this reason we need to use
@@ -293,26 +293,26 @@ names are really available and needed in the current namespace.

- Be as specific as possible when catching exceptions
- Keep try-blocks as small as possible
- Don't use `except:` (Slighlty better for special cases: `except Exception`)
- Don't use `except:` (Slightly better for special cases: `except Exception`)

### Paths and files

- Use `pathlib2` / `pathlib` (in python 3). To be more future-proof, import like this:
- Use `pathlib2` / `pathlib` (in Python 3). To be more future-proof, import like this:

```
from pathlib2 import Path
```

- Use `with` to open files
- Use context-managers (the `with` keyword) to open files.
- You are welcome to refactor old style file IO to pathlib (with tests :-))

### String formating
### String formatting

- Use classic format strings (`%s`) for the time being. We'll move over to the
new `format()` syntax in the future, but for the moment we'd like to stay
consistent.

### Subprocesses
### Sub processes

- Use mechanisms that are natively available in Python instead of
subprocess/command line tools. Example: Don't use `tar` command line tools.
@@ -349,8 +349,8 @@ names are really available and needed in the current namespace.

### Comments

- Document the non-obvious. Don't document the how, do document the why
- Use doc strings for classes and methods.
- Document the non-obvious. Don't document the how, do document the why.
- Use doc-strings for classes and methods.

### Code structuring

@@ -376,8 +376,8 @@ names are really available and needed in the current namespace.
in disguise, so we should not use them like that.
- A `class` with mypy type annotations: This is the optimum. Now we're
talking OO and mypy can help us tremendously during e.g. refactorings.
- Don't use global variables except you have to
- Don't assign variables to function namespace
- Don't use global variables unless you have to and can do so thread-safe.
- Don't assign attributes to function objects.
- Use `abc` for specifying abstract classes, methods and properties and add
`raise NotImplementedError()` in abstract methods and properties)
- Make class attributes explicit in the constructor or helper functions (Don't
@@ -387,7 +387,7 @@ names are really available and needed in the current namespace.
access make use of `@property`
- Use `@staticmethod` and `@classmethod` decorators for methods without
references to `cls` or `self`
- Use early exits in your functions
- Use early exits in your functions.

### Module: cmk
* The entire Python code of Checkmk should be under the main module `cmk` in
@@ -438,15 +438,15 @@ project repository, where YAPF picks it up automatically. YAPF itself lives in
a virtualenv managed by pipenv in `check_mk/virtual-envs/2.7/.venv`, you can run it with
`make format-python` or `scripts/run-pipenv run yapf`.

#### Manual invocation: Single file ===
#### Manual invocation: Single file

```
yapf -i [the_file.py]
```

#### Manual invocation: Whole code base

If you want to format all python files in the repository, you can run:
If you want to format all Python files in the repository, you can run:

```
make format-python
@@ -460,14 +460,14 @@ Our CI executes the following formatting test on the whole code base:
make -C tests test-format-python
```

Our review tests jobs prevent unformatted code from being added to the
Our review tests jobs prevent un-formatted code from being added to the
repository.

#### Editor integration: *macs
- plugins for vim and emacs with installation instructions can be found here:
https://github.com/google/yapf/tree/master/plugins
- in Spacemacs yapfify-buffer is available in the python layer; formatting on
- in Spacemacs yapfify-buffer is available in the Python layer; formatting on
save can be enabled by setting ''python-enable-yapf-format-on-save'' to
''t''
- In Emacs with elpy call the function 'elpy-yapf-fix-code'. Because there
@@ -476,9 +476,9 @@ repository.
#### Editor integration: vim
- It is recommended to use yapf as fixer for [ALE](https://github.com/w0rp/ale)
- It is recommended to use yapf as fixer for [ALE](https://github.com/dense-analysis/ale)
In der `~/vimrc` YAPF als Fixer konfigurieren (fixt nach dem speichern):
Configure YAPF as fixer in your `~/vimrc`. This way the file gets fixed on every save:
```
let g:ale_fixers = {'python': ['isort']}
@@ -554,7 +554,7 @@ about the error diagnosis below, if it doesn't work.
```
## Styleguide: Shell scripts
## Style guide: Shell scripts
The Linux / Unix agents and several plugins are written in shell code for best
portability and transparency. In case you want to change something respect the
@@ -39,7 +39,7 @@ To prepare your system for building, you need to execute this command:

This will install the missing build dependencies, at least if you are working on
a supported Linux distribution. Then you can either create RPM or DEB packages,
depending on your distro.
depending on your Linux-distribution.

To build an RPM:

0 comments on commit 7fa2fc3

Please sign in to comment.
You can’t perform that action at this time.