Mercurial > irccd-www
annotate versioning.md @ 32:2cd3c88e9f1a
change manual page styles
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 17 Dec 2020 12:34:53 +0100 |
parents | 08131face9d0 |
children | 82badbee34d1 |
rev | line source |
---|---|
22
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 % irccd - versioning |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 % David Demelier <markand@malikania.fr> |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 % 2019-07-10 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 |
29
08131face9d0
switch to no-class.css
David Demelier <markand@malikania.fr>
parents:
22
diff
changeset
|
5 Versioning |
08131face9d0
switch to no-class.css
David Demelier <markand@malikania.fr>
parents:
22
diff
changeset
|
6 ========== |
22
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 Irccd follows [Semantic Versioning][semver] for the following components. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 Configuration file |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 ------------------ |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 The configurations files **irccd.conf** and **irccdctl.conf** MUST stay |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 compatible all the lifetime of a major version. If a configuration file is |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 created for irccd 2.4.5, then it MUST always work with irccd 2.8.0. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 Compatibility may be altered in the next major version. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 Deprecation of configuration options is allowed and noted as well in related |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 documentation. The user is encouraged to change its configuration files. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 Javascript API |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 -------------- |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 The provided Javascript API MUST remain compatible as well all the lifetime of a |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 major version. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 It is possible to update existing functions as they don't break backward |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 compatibility such as: |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 - Adding a new parameter at the end of arguments, |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 - Returning an object while the function was returning undefined formerly, |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 - Throwing new kind of exception, Javascript has no by-type exception handling |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 so this does not break user code, |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 - Taking a different parameter type as long as the other signature remains valid. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 Plugins |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 ------- |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 All plugin configurations are subject to the same terms as irccd configuration |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 files. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 In additions to the configurations, each plugin MUST keep backward compatible |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 usages when invoking commands. Adding new arguments and features is possible in |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 minor versions. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 Plugin message formats MUST still exist until the next major version but they |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 MAY write different messages in any new version. This is intentional as they can |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 contain typos. Users SHOULD NOT parse default formatted messages if this is a |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 concern. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 Socket transport protocol |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 ------------------------- |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 The network messages for communicating with irccd daemon MUST be backward |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 compatible in any new minor or patch versions. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 Depractions of commands MUST be documented and an alternative SHOULD be proposed |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 to the user if applicable. Irccd stay silent in network responses when issuing |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 deprecated commands so the user SHOULD read the **CHANGES.md** from the project |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 directory or announcements from time to time. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 Adding new properties in JSON object **is not** considered as a breaking change. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 Build system |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 ------------ |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 All user definable options in irccd CMake build system MUST remain valid until |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 the next major version. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 New options MAY be added in new minor versions. Deprecated options are noted as |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 well in annoucements or **CHANGES.md**. |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 |
e49c41217e6e
create new minimal website
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
73 [semver]: http://semver.org/ |