Hello 👋

Dear @asterisk-java/contributors, @asterisk-java/owners and everyone who want to support us!

I would like to invite all of you to this conversation.
These are the next steps of making the asterisk-java project great again.

❗ Disclaimer

This is only a proof-of-concept and should be treated as a proposal and a base for the discussion.

_{I hope responses will be faster.}

‼️
If you don't agree with any changes or proposals, let me know by using the reaction button, or more helpfully, by giving constructive feedback on what is wrong and how it should be handled.

I've diagnosed a couple of problematic areas.

1. Code maintenance and releases

💥 Problems:

• Right now, releases are done by some weird Dart release scripts, which are neither Java nor GitHub friendly.
• We don't have any changelog. Nowadays, this is bad practice and very uninformative.
• In addition, a lot of changes are made without any issue or even a short description of the reason for changes.

💡 Solutions:

• Do release using GitHub Releases connected with GitHub Actions and Maven Release Plugin (or another way, but using Java).
• GitHub Releases helps us with the changelog.
• All changes must have an appropriate issue or pull request with a short description. Master (maybe main?) should be blocked for direct pushes. Every change should be done via pull requests (for everyone!) and reviewed.

2. Project structure

💥 Problems:

• Right now everything is mixed into one module. If you want to run only fastagi or manager - you can't.
• There aren't boundaries between modules.

💡 Solutions:

I suggest the following project structure:

asterisk-java-parent        (POM)
├── asterisk-java-agi       (POM)
│   ├── asterisk-java-agi-asyncagi  (JAR)    dependencies: asterisk-java-agi-command, asterisk-java-agi-core, asterisk-java-ami-manager
│   ├── asterisk-java-agi-command   (JAR)
│   ├── asterisk-java-agi-core      (JAR)
│   └── asterisk-java-agi-fastagi   (JAR)    dependencies: asterisk-java-agi-core, asterisk-java-agi-command
├── asterisk-java-ami       (POM)
│   ├── asterisk-java-ami-action    (JAR)
│   ├── asterisk-java-ami-event     (JAR)
│   └── asterisk-java-ami-manager   (JAR)   dependencies: asterisk-java-ami-action, asterisk-java-ami-event
├── asterisk-java-common    (JAR)
├── asterisk-java-live      (JAR)           dependencies: asterisk-java-ami-manager
└── asterisk-java-pbx       (JAR)           dependencies: asterisk-java-agi-fastagi, asterisk-java-ami-action, asterisk-java-ami-event

Why are modules good?

• They give an overview of how asterisk-java and Asterisk itself are designed. They also provide boundaries of responsibility.
• Prevent mixing objects (exceptions, models, etc.) between modules.
• Gives possibility to extend in the future (we can easily add e.g. ARI module).

3. Supported versions

💥 Problems:

Currently the project doesn't have clearly defined Asterisk and Java supported versions.

💡 Solutions:

Java

• All LTS versions shlould be supported and tested (8, 11, 17).
• If any Java version becomes EOL, we should drop support in the next major release (for Java 8 it's 2025-03-31).

Asterisk

For Asterisk versions 16, 18 and 20 the major should be 4.x.x. When 16 reaches its EOL in 2023-10-09, we should change
the major to 5.x.x. We should also change the major version when a new Asterisk LTS version is released.

asterisk-java project release cycle:

❗ Disclaimer

With this release process I have a lot of confusion. I'm not 100% sure it's a good way to do it.

4. Labels

💥 Problems:

• Without labels, we cannot make any automation.
• Also issues and pull requests are uncategorized.

💡 Solutions:

Create labels and use it.

Connected with particular Asterisk version.

asterisk/16
asterisk/18
asterisk/20
...

Type of issue or pull request.

kind/bug
kind/breaking
kind/dependencies
kind/documentation
kind/enhancement
kind/feature
kind/question
kind/refactor
kind/wontfix

Additional information for issue or pull request.

meta/skip-changelog

Connected for particular module.

module/agi
module/ami
module/live
module/pbx

5. Cleanup branches

💥 Problem:

There is a bunch of the stale branches.

💡 Solution:

Remove all of them, and leave only master.

6. Integration tests

💥 Problem:

Right now, there aren't any integration tests. We are not sure that our lib working with supported Asterisk versions.

💡 Solution:

We should running integration test for each supported Asterisk version. To achieve this, we can use Testcontainers.

Here is a proof-of-concept of super easy and a little bit dumb example, but this prove it's possible to run integration tests automatically.

piotrooo@dbefe8b

Tests should be run for all supported Asterisk versions.

7. Web page asterisk-java.org

💥 Problem:

Web page is very outdated.

💡 Solution:

• Create new web page with introduction, modules overview, documentation, some explanations.
• We should use some static site generator like MkDocs or AsciiDoc or some other.

8. Logo

💥 Problem:

Last but not least, asterisk-java doesn't have own logo 😭

💡 Solution:

I've asked my good friend @tomekbbk, who is also a graphic and UX designer in company where I've working, to create logo.
This is what he designed for us:

BTW. Connect Java coffee cup with Asterisk logo = FTW 🤩

How should we start?

In my opinion

1. Create labels for issues and pull requests and start to use them
2. Cleanup release cycle - use maven plugin and generate change log (GitHub Actions and GitHub Releases)
3. Block master for direct pushes
4. Cleanup stale branches
5. Try to address and fix at least couple of issues
6. Modularize project
7. Add integration tests
8. Web page

After that changes, version 4.0.0 should be #released!

If something needs more clarification let me know. I'll try to response.