To create new wiki account, please join us on #znc at freenode and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

Difference between revisions of "Ideas"

From ZNC
Jump to: navigation, search
m (add a note and link to github)
(Releasing and branching model)
Line 26: Line 26:
  
 
[[User:Jpnurmi|J-P Nurmi]] ([[User talk:Jpnurmi|talk]]) 13:50, 7 March 2014 (CET)
 
[[User:Jpnurmi|J-P Nurmi]] ([[User talk:Jpnurmi|talk]]) 13:50, 7 March 2014 (CET)
 +
 +
 +
== Releasing and branching model ([[User:jpnurmi|jpnurmi]]) ==
 +
 +
Predictable releases and versions are important for such stakeholders as Linux packagers. The current release model, where every release is an incompatible major release, makes it a bit unattractive to update ZNC. I'd like to propose switching to a "ZNC compatible interpretation" of [[http://semver.org semantic versioning]]. It has become almost like an industry standard, and for what it's worth, it's also recommended by [[https://help.github.com/articles/creating-releases GitHub]]. The whole releasing process involves branching and versioning, and results to certain level of [[http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++ compatibility promise]] as discussed below.
 +
 +
==== Major version ====
 +
 +
A new major version (eg. 2.0.0) is introduced when it's a time for a serious overhaul (eg. fixing an architectural shortcoming). A major version _may_ introduce any sort of breaks. Any deprecated API may be removed, and the existing API might undergo major changes. A major version is also a good opportunity for a general cleanup.
 +
 +
What comes to obtrusive ideas that are not compatible with the current major version (eg. 2.x series), it's often a good idea to add easy to search TODO comments in relevant places in the code, write down the ideas somewhere, or use feature branches (preferably personal forks) to prepare an implementation of the feature for the next major version.
 +
 +
==== Minor version ====
 +
 +
A new minor version (eg. 2.1.0) _may_ introduce ABI (binary) incompatible changes (eg. adding new virtual module hooks). However, minor versions shall be still kept backwards _source_ compatible meaning that existing modules can be rebuilt without changes to the module source code. In principle, new types and methods may be introduced, but any existing API _must not_ be removed or changed in source incompatible way. Old types and methods may be marked as deprecated but _must_ remain functional to some degree (common sense applies here).
 +
 +
==== Patch version ====
 +
 +
A new patch version (eg. 2.0.1) aka "bug fix release" _must not_ introduce any ABI (binary) incompatible changes. This ensures that existing modules keep running without the need of rebuilding them. In practice this means that only bug fixes to the internal implementation are allowed. In principle, public API changes are a no go.
 +
 +
==== Branches ====
 +
 +
Depending on the situation, master forms the next minor or major version. New features are always pushed to master. The preparation of a major or minor release starts by branching it from master. Meanwhile, feature development of the next major or minor version continues in master. Non-obtrusive bug fixes are always pushed to the latest applicable and supported version branch. These version branches are periodically merged to the next version branches and eventually master. The following chart illustrates a branching model based on semantic versioning:
 +
<pre>
 +
master _____2.1_________________2.2____________________________2.3/3.0__ ...
 +
          \            ^    \                            ^
 +
          \          /      \                          /
 +
2.0        v__2.0.0__/__2.0.1__v__2.0.2_______...        /
 +
                                \        \            /
 +
                                  \        \          /
 +
2.1                                v__2.1.0__v__2.1.1__/__2.1.2__ ...
 +
</pre>
 +
[[User:Jpnurmi|J-P Nurmi]] ([[User talk:Jpnurmi|talk]]) 16:39, 7 March 2014 (CET)
 +
  
  
Line 35: Line 69:
 
* optionally, forwarding convenience headers: ZBuffer, ZChannel, ZNetwork, ZString... (no .h, includes the actual header)
 
* optionally, forwarding convenience headers: ZBuffer, ZChannel, ZNetwork, ZString... (no .h, includes the actual header)
 
This way module developers would know exactly what to include. :)
 
This way module developers would know exactly what to include. :)
~~~~
 
-->
 
 
<!-- TODO: rewrite
 
== Semantic "major.minor.patch" versioning ([[User:jpnurmi|jpnurmi]]) ==
 
* major = major changes
 
* minor = new features
 
* patch = bug fixes only
 
See http://semver.org for more details.
 
~~~~
 
-->
 
 
<!-- TODO: rewrite
 
== Binary/source compatibility ([[User:jpnurmi|jpnurmi]]) ==
 
* a new major version allowed to be SC incompatible
 
** API changes, cleanup any deprecated stuff
 
** modules need to be updated
 
* a new minor version allowed to be BC incompatible
 
** may introduce new methods & overloads, keep but deprecate old ones
 
** modules need to be rebuilt
 
* a new patch version should be BC/SC compatible
 
** bug fixes only
 
** modules keep working without rebuilding
 
 
~~~~
 
~~~~
 
-->
 
-->

Revision as of 15:39, 7 March 2014

This page collects random ideas for the future development of ZNC. Everyone is welcome to add their ideas on the list. Please tag each idea with your username.

Note: Feature requests should be filed at GitHub.

Disclaimer: Some of the ideas are not going to be taken seriously, some are shot down right away, and some might even cause fuss and anger. Yet, please put emotions aside and try to be constructive with your comments.

Project structure (jpnurmi)

Modularity and extensibility is admittely one of the key ingredients in ZNC's recipe for success. These days there is a ZNC module for pretty much any imaginable IRC task. Therefore modules deserve to be treated as first class citizens, with good care. ;)

Related to versioning and compatibility as discussed below; since ZNC offers no stable module API and only does major feature releases, modules have somewhat high tendency to break on every ZNC version upgrade. This in turn makes such stakeholders as Linux distributions and ZNC hosting providers resistant to upgrade to the latest version. A stable module API would not only help module developers, but also anyone hosting a ZNC service.

In order to achieve a stable module API, the ZNC core could be refactored so that the core types would be gradually moved to a separate library. It would be nice to make it a separate build unit to avoid undesired backwards dependencies to the ZNC application code.

  ___________         ___________
 /  ZNC app  \       /  ZNC lib  \        ___________
|             |     |             |      /           \
| - main()    | --> | - CModule   | <-- | ZNC modules |
| - CModules  |     | - CString   |      \___________/
| - ...       |     | - ...       |
 \___________/       \___________/
 

Notice that the library should be absolutely minimal. Most importantly, the public API should not contain anything ZNC application specific. That library would then eventually act as an interface for modules. This restructuring would greatly help maintaining a stable module API in the future, and thus make modules much less prone to break. ZNC would have full control over what modules have access to ie. modules would no longer be able to mess with ZNC internals that have no promise of API compatibility.

J-P Nurmi (talk) 13:50, 7 March 2014 (CET)


Releasing and branching model (jpnurmi)

Predictable releases and versions are important for such stakeholders as Linux packagers. The current release model, where every release is an incompatible major release, makes it a bit unattractive to update ZNC. I'd like to propose switching to a "ZNC compatible interpretation" of [semantic versioning]. It has become almost like an industry standard, and for what it's worth, it's also recommended by [GitHub]. The whole releasing process involves branching and versioning, and results to certain level of [compatibility promise] as discussed below.

Major version

A new major version (eg. 2.0.0) is introduced when it's a time for a serious overhaul (eg. fixing an architectural shortcoming). A major version _may_ introduce any sort of breaks. Any deprecated API may be removed, and the existing API might undergo major changes. A major version is also a good opportunity for a general cleanup.

What comes to obtrusive ideas that are not compatible with the current major version (eg. 2.x series), it's often a good idea to add easy to search TODO comments in relevant places in the code, write down the ideas somewhere, or use feature branches (preferably personal forks) to prepare an implementation of the feature for the next major version.

Minor version

A new minor version (eg. 2.1.0) _may_ introduce ABI (binary) incompatible changes (eg. adding new virtual module hooks). However, minor versions shall be still kept backwards _source_ compatible meaning that existing modules can be rebuilt without changes to the module source code. In principle, new types and methods may be introduced, but any existing API _must not_ be removed or changed in source incompatible way. Old types and methods may be marked as deprecated but _must_ remain functional to some degree (common sense applies here).

Patch version

A new patch version (eg. 2.0.1) aka "bug fix release" _must not_ introduce any ABI (binary) incompatible changes. This ensures that existing modules keep running without the need of rebuilding them. In practice this means that only bug fixes to the internal implementation are allowed. In principle, public API changes are a no go.

Branches

Depending on the situation, master forms the next minor or major version. New features are always pushed to master. The preparation of a major or minor release starts by branching it from master. Meanwhile, feature development of the next major or minor version continues in master. Non-obtrusive bug fixes are always pushed to the latest applicable and supported version branch. These version branches are periodically merged to the next version branches and eventually master. The following chart illustrates a branching model based on semantic versioning:

master _____2.1_________________2.2____________________________2.3/3.0__ ...
          \             ^     \                             ^
           \           /       \                           /
2.0         v__2.0.0__/__2.0.1__v__2.0.2_______...        /
                                 \         \             /
                                  \         \           /
2.1                                v__2.1.0__v__2.1.1__/__2.1.2__ ...

J-P Nurmi (talk) 16:39, 7 March 2014 (CET)