CONTRIBUTING.md 5 KB
Newer Older
1 2 3 4 5 6 7
# CONTRIBUTING

Thank you for taking the time to contribute to Cloogle. Please read this before
contributing to avoid wasting your or our time.

---

8 9
1. [Bug reports](#1-bug-reports)
2. [Submitting patches](#2-submitting-patches)
10
3. [I just want to add library X](#3-i-just-want-to-add-library-x)
11
4. [I just want to add a new user agent to the statistics](#4-i-just-want-to-add-a-new-user-agent-to-the-statistics)
12 13 14 15 16

---

## 1. Bug reports

17
We use GitLab issues for bug tracking.
18

19 20
First, check if your bug has been reported already. If not, open a new issue.
Make sure to include the following:
21

Camil Staps's avatar
Camil Staps committed
22 23 24 25
- Steps to reproduce
- Actual outcome
- Expected outcome
- How you're accessing Cloogle (through the frontend or directly to Clean)
26

27
**If you have found a security vulnerability**, please do **not** open an
Camil Staps's avatar
Camil Staps committed
28 29 30
issue. Instead, contact one of the maintainers (see the list in `README.md`).
We will take immediate action.

31 32
## 2. Submitting patches

33 34 35 36 37
### Which repository to patch

- [libcloogle][] describes the Cloogle API as a set of types. Because many
  applications make assumptions about this API, one must be reluctant with
  changing this. However, sometimes it is necessary. See
38
  [`CONTRIBUTING.md`](https://gitlab.science.ru.nl/cloogle/libcloogle/blob/master/CONTRIBUTING.md)
39
  in that repository for more details.
40 41
- [Cloogle][] contains the core functionality for indexing and searching.
- This repository ([cloogle.org](https://gitlab.science.ru.nl/cloogle/cloogle-org))
42 43 44
  is only a wrapper around [Cloogle][]. It contains functionality for TCP,
  caching, the web frontend and statistics.

45 46
### General

47
- Fork the repo, make a topic branch and when done submit a pull request.
Camil Staps's avatar
Camil Staps committed
48
- If your PR fixes some issue, be sure to mention it in the commit message
49
  (e.g. `Fix #15`).
Camil Staps's avatar
Camil Staps committed
50 51 52 53 54
- Keep PRs as focused as possible. If you intend to fix multiple, independent
  things, open multiple, separate PRs.
- If you intend to make large changes, it's probably best to open an issue and
  discuss with the maintainers first.
- If necessary, edit `README.md` as well.
55 56 57

### Code style

58 59
- Use tabs instead of spaces.
- Try to keep lines under 80 chars (except for HTML).
Camil Staps's avatar
Camil Staps committed
60 61
- When editing the frontend, do not use external frameworks (jQuery,
  bootstrap, etc.). We strive for minimality and elegance.
62 63 64

### Other stuff

65
- Add yourself to the authors list in `README.md`.
66 67

## 3. I just want to add library X
68
If the library is not well-known it is advised to first open an issue to see
69 70
whether it is suitable to be indexed by cloogle.

Camil Staps's avatar
Camil Staps committed
71 72 73 74 75 76 77 78 79 80 81 82
### Preparation
Your library will be most easily accessible when:

- Functions, type definitions, classes and modules are documented. For details
  on the documentation format, see
  [DOCUMENTATION.md](https://gitlab.science.ru.nl/clean-and-itasks/clean-platform/blob/master/doc/DOCUMENTATION.md)
  in Platform.
- Macros have types using the `@type` documentation field.

Having documentation is not a strict requirement, however.

### Updating the index
83 84
To add a library you have to modify [`libs.json`](/libs.json). This file is a
JSON record with three collections of Clean libraries. Usually, you should add
85 86 87 88
the new library to the `Miscellaneous` collection. Please keep the alphabetic
order intact.

The newly added item may contain the following fields:
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109

- `name` (**required**): a human-readable name.
- `fetch_url` (**required**): choose one of:
  - `["Git", "<URL>"]` where `<URL>` points to a public git repository;
  - `["SVN", "<URL>"]` where `<URL>` points to a public Subversion repository;
  - `["CleanDistribution", "<NAME>"]`, if the library is distributed in Clean
    nightlies as `<NAME>`.
- `path`: the path from the root of the repository to the files that should be
  indexed.
- `info_url`: a URL to an informative page about the library.
- `pattern_exclude`: a pattern (see below) for files to exclude.
- `pattern_app`: a pattern (see below) for modules that should be marked as
  apps rather than libraries.
- `pattern_core`: a pattern (see below) for modules that are part of the core
  of the library.

Patterns are JSON lists of simple patterns. A simple pattern is one of:

- `["PWildcard"]`, to match everything;
- `["PStartsWith",<S>]`, to match paths starting with `<S>`;
- `["PNot",<P>]`, to negate the simple pattern `<P>`.
110 111 112

## 4. I just want to add a new user agent to the statistics
If you have created a new Cloogle client, please give it a specific user agent
113 114 115 116
and add it to the `$user_agents` array in `frontend/stats/ajax/conf.php`. That
way, it will show up in the statistics on
https://cloogle.org/stats/longterm.html. There are no strict naming
conventions, but you can have a look at the other user agents for inspiration.
117 118 119 120 121 122

Each entry has a key, which is the name of the client (e.g. 'vim-clean'). The
value is an array with a required `pattern`, which is used in SQL `LIKE`
queries so you can use `%` as in `%Linux%` - in most cases, the pattern will be
equal to the name. The optional `url` is a link to where the client may be used
or downloaded.
123

124 125
[Cloogle]: https://gitlab.science.ru.nl/cloogle/Cloogle
[libcloogle]: https://gitlab.science.ru.nl/cloogle/libcloogle