mautic / mautic-community-handbook

A handbook for all things related to the Mautic Community

About Mautic

Mautic is the world’s largest open source marketing automation project. With over 200,000 organisations using Mautic and over 1,000 community volunteers, we empower businesses by making it easy to manage their marketing across a range of channels. Stay up to date about initiatives, releases and strategy via our blog.

Marketing automation has historically been difficult to implement within organisations. The Mautic Community is an example of open source at its best, offering great software and a vibrant and caring community in which to learn and share knowledge.

Open source means more than open code. Open source provides equality for all and a chance for everyone to improve.

Get Involved

Before we tell you how to install and use Mautic, we like to shamelessly plug our awesome user and developer communities! Users, start here for inspiration, or follow us on Twitter @MauticCommunity or Facebook @MauticCommunity. Once you’re familiar with using the software, maybe you will share your wisdom with others in our Slack channel.

Calling all devs, testers and tech writers! Technical contributions are also welcome. First, read our general guidelines about contributing. If you want to contribute code, read our CONTRIBUTING.md or Contributing Code docs then check out the issues with the T1 label to get stuck in quickly and show us what you’re made of.

If you have questions, the Mautic Community can help provide the answers.

Installing and using Mautic

Supported Versions

Please check the latest supported versions on the Mautic Releases page.

Software Downloads

The GitHub version is recommended for both development and testing. The production package (including all libraries) is available at mautic.org/download.

Installation

Disclaimer

Install from source only if you are comfortable using the command line. You'll be required to use various CLI commands to get Mautic working and keep it working. If the source/database schema gets out of sync with Mautic releases, the release updater may not work and will require manual updates. For production, we recommend the pre-packaged Mautic which is available at mautic.org/download.

Also note that source code outside of a tagged release should be considered ‘alpha’. It may contain bugs, cause unexpected results, data corruption or loss, and is not recommended for use in a production environment. Use at your own risk.

How to install Mautic

You must already have Composer available on your computer because this is a development release and you'll need Composer to download the vendor packages.

Also note that if you have DDEV installed, you can run 'ddev config' followed by 'ddev start'. This will kick off the Mautic first-run process which will automatically install dependencies and configure Mautic for use. ✨ 🚀 Read more here

Installing Mautic is a simple three-step process:

1. Download the repository zip then extract the zip to your web root.
2. Run the composer install command to install the required packages.
3. Open your browser and complete the installation through the web installer.

If you get stuck, check our our general troubleshooting page. Still no joy? Join our lively Mautic Community for support and answers.

User Documentation

Documentation on how to use Mautic is available at docs.mautic.org.

Developer Docs

Developer documentation, including API reference docs, is available at developer.mautic.org.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Dennis Ameling 💻 📓	Mohammad Abu Musa 💻 📓 👀	John Linhart 📓 👀 💻 ⚠️	Norman Pracht - Webmecanik 📓 💻	Zdeno Kuzmany 📓 👀 💻 ⚠️	Steve Robinson 📓 🐛	Petr Šnobl 💻 🐛
Lukas Günther 💻 📖 📓	Ruth Cheesley 📓 👀 📖	Anton Vlasenko 💻 ⚠️	Miroslav Fedeleš 💻 ⚠️ 📓 👀	gabepri 🐛 💻	incentfit 📓	Lukáš Drahý 💻 👀
Alan Hartless (he/him) 💻	Mohit Aghera 💻 📓 👀	Dom Parry 📓	sensalot 📓	Rahul Shinde 👀 📓 💻	jos0405 💻 📓	Nick Veenhof 👀
Patryk Gruszka 💻 📖 ⚠️ 👀 📓	Alex Hammerschmied 💻 📓	Dirk Spannaus 🐛 📓	Rehan Nischal 🐛	Christophe9880 📓	Saurabh Gupta 💻 👀	Tejas Navghane ⚠️ 💻 📓 👀
Florent Petitjean - Webmecanik 📓	Oluwatobi Owolabi 📋	Favour Kelvin 📖 ✅ 📢	Giovanni Mascellani 💻	Raphael van der Woude 📓	mannp 🐛 📓	MarketSmart 💻
Leon 📓	bryanitamazonva 🐛	n-azimy 💻	Ikko Ashimine 💻	Max Lawton 💻 📖	Rohit Pavaskar 💻	Disha P 💻
Adrian 👀 📓 💻	vijayhrdm 🐛	julienWebmecanik 💻	Johan Buchert 📓	TS16V 🐛	rafalsk 🐛	Jonathan Dahan 🐛
j26w 📓	Theodoros Ploumis 💻	Sreenivasulu Avula 📓 👀	Mohammad Lahlouh 📓	ArnaudSau 💻	Andrew Bell 📓	Alfredo Arena 💻
mollux 💻	ekkeguembel 📓	Madlen 📓	Kathrin Schmid 🌍	Rahul Dhande 💻	Artem Lopata 📓 👀 💻	Anthony Bailey 💻
Eloi Marques da Silva 💻	Tomasz Kowalczyk 💻	jensolsson 📓	Tony Bogdanov 💻	Brady Cargle 📓	mmarton 📓	bodrak 💻
nick-vanpraet 💻	Volha Pivavarchyk 📓 💻	Nish Joseph 💻	Damzoneuh 💻	alinmbb 💻	Déborah Salves 📓	automatyzuj 📓
KN4CK3R 💻	Benjamin Lévêque 💻	Benjamin 💻	Iris Amrein 📓	peter.osvath 💻	poweriguana 📓 📆	OnyXxL 📓
Dominik Lacković 📓	Omer Toledano 📓	ZebruhDivs 📓	Alan Wierzchoń 💻	Tomazz Jurich 📓	putzwasser 🐛	erk 📓
Daniel 📓	agencia904 📓	mbfds 📓	Lucas Lazarini 📓	Gonzalo Cao Cabeza de Vaca 📓	Robmobius 📓	Marc Beinder 💻
bergwerkweb 💻	Rembrand 📓 💻 👀	TechBill 📓	Irfan Hanfi 💻	Anna Munk 💻	Sven Döring 📓	Pedro de Jesus 💻
Jean-Marc 📓	Paul Sanduleac 💻	Lenon Leite 💻	Alan Syrgak 📓	Mohammed Header 💻	Dana Linhartová 💻	Thanks ⚠️
Patrick 📓	Tomas Votruba 💻	Tirtharaj Ghosh 📖	Ruben Nogueira 💻	Oleh Vanin 👀	Tim Mallezie 💻	Markus Staab 💻
code5rick 🐛 💻	jcrandell7 📓	Jason Woods 💻	Enkhjargal Lkhagvaa 👀	alexbusu-motork 👀	David Gorges 🐛 💻	Gernot Pansy 🐛 💻
andersonjeccel 💻 ️️️️♿️ 📖 🐛 👀 📓 🎨 📆	Alexei Pl 🐛 💻	Alvaro 🐛	Ajit 💻 🐛	Esthertests 👀	magdalenaleonow 🐛	Priyanshi Gaur 💻
Damian 👀 🐛	Markus Heinilä 👀	Juan Gadiel Rosado Colon 🐛 📓

This project follows the all-contributors specification. Contributions of any kind welcome!

mautic-community-handbook's Issues

Add a section under structure to explain teams, working groups, initatives and tiger teams

At present we don't have any info on the handbook about how all the entities in the community work together - teams, working groups, initiatives, tiger teams etc.

The info was shared in my keynote in November and is on mautic.org / on Confluence.

We should add this to the structure section to give an outline of how it all fits together, but also have some references in the How to Contribute section which is more about how to get started, who the key people are to contact, etc.

Remove references to Acquia in writing for mautic docs

https://github.com/mautic/mautic-community-handbook/blob/main/pages/15.contributing/06.Writer/docs.md

This page needs updating/consolidating and importantly, removing references to Acquia.

Navigation issue on "How is Mautic used?"

Clicking on Next button on "How is Mautic used?" page, takes me to Code of Conduct in stead of "How can I try Mautic?".

Not sure how the system works but I guess the issue is related to lack of category in that page.

Update council page

We need to update the council page with this information: https://www.mautic.org/mautic-council.

Add a sub-section under Google Summer Of Code

New Subsection Under GSoC

Purpose

This subsection aims to serve as a document for current and past year Google Summer of Code (GSoC) ideas, as well as potential ideas for Google Season of Docs (GSoD) [In Future] . By incorporating this subsection into our documentation, we provide valuable information to newcomers about ongoing and past GSoC projects. Additionally, it serves as a means to showcase our accomplishments in GSoC and potentially GSoD in the future.

Proposed Content

• Current Year GSoC Ideas: A list of project ideas for the current year's GSoC program.
• Past Year GSoC Ideas: A compilation of project ideas from previous years' GSoC editions. [Year Wise]
• Potential GSoD Ideas: Suggestions for projects that could be undertaken in Google Season of Docs. [In Future]

Benefits

• Information Accessibility: Newcomers will have easy access to information regarding ongoing and past GSoC projects, fostering awareness and interest.
• Accomplishment Showcase: By documenting past GSoC projects, we highlight the organization's achievements and contributions to open source development.
• Future Planning: The inclusion of potential GSoD ideas enables us to prepare for future participation in the program and expand our contributions to documentation.

Implementation Plan

1. Documentation Update: Introduce the new subsection within our documentation structure, clearly outlining its purpose and contents. Google Doc Link For Content
2. Regular Updates: Maintain the subsection by updating it with new GSoC ideas each year and revising past ideas as necessary.
3. Promotion and Awareness: Publicize the existence of the subsection to the community, encouraging participation in GSoC and GSoD initiatives.

Additional Suggestions

• Success Stories: Incorporate success stories from past GSoC and GSoD participants to inspire and motivate prospective contributors.

Conclusion

The addition of a GSoC and GSoD subsection to our documentation not only enhances information accessibility but also strengthens our engagement with these valuable programs. By showcasing our involvement and accomplishments, we demonstrate our commitment to fostering open source collaboration and community growth.

Write documentation for Community Portal explaining registration fields on events

You have to save the form and the description first, and THEN you need to add the fields.

Originally posted by @RCheesley in mautic/Community-Portal#31 (comment)

Update reference to index_dev.php on developer mode section

There's an outdated reference here:

https://contribute.mautic.org/contributing-to-mautic/tester?_gl=1*1in3zx3*_ga*NDQ4MTgzODAxLjE3MDY2MjAyNjQ.*_ga_ZRB8436CFL*MTcwNjcwMTE5MS43LjEuMTcwNjcwMTI3NC4zOC4wLjA.#using-developer-mode

This should refer to the .env file now.

Using Mobilizon open source software instead of proprietary Meetup.com

While Mautic is an amazing open source project, meetup is fully proprietary and some community members might not feel comfortable feeding it with content. An alternative to meetup is Mobilizon:
"Mobilizon is an open source software for event planning and group management, launched in October 2020 by Framasoft to offer a free alternative to the platforms of GAFAM (Facebook, Meetup.com, EventBrite). Mobilizon gained much visibility in hacker circles relatively fast, but also soon within cultural scene in Europe and more recently in the mainstream IT media."

I am aware that migrating from platforms like meetup is not easy, especially when a community is established there, but given the open source ethos of Mautic I think it would make sense to consider migrating to FLOSS platforms like Mobilizon or something similar.
Just my two cents.

Add a note about Psysh being available

Starting with Mautic 3.1, Psysh is available for developers. This information is useful to add to Contributing > Developer > Code > Pull Requests https://contribute.mautic.org/contributing-to-mautic/developer/code/pull-requests. More details can be found in this PR: mautic/mautic#6667

Update required for forums link

The Mautic Forum link in 'Apply' Section in sub topic 'Google Summer Of Code' is incorrect.

Initial: https://forums.mautic.org/
Update: https://forum.mautic.org/
Check Here

The TOC link to Step 2 of the Pull requests page is broken

Hey.

When viewing the Pull requests page on https://contribute.mautic.org/contributing-to-mautic/developer/code/pull-requests the link to Step 2: Feature? Check the roadmap & Feature Requests in the TOC is broken, despite it working perfectly when viewing the page on https://github.com/mautic/mautic-community-handbook/blob/master/pages/13.contributing/02.developer/01.Code/02.Pull%20requests/docs.md

I looked into it and it turns out the TOC is linking to #step-2-feature-check-the-roadmap--feature-requests, which apparently works fine when viewing the page on GitHub, but apparently in Grav the working link to the section instead becomes #step-2-feature-check-the-roadmap-feature-requests (with only a single - after 'roadmap') and thus causing the TOC link to not work.

To make things even more confusing, I tried generating a TOC with the link from the source code - https://ecotrust-canada.github.io/markdown-toc/ - and according to that, the section link should be #step-2--feature--check-the-roadmap---feature-requests - i.e. with even more extra hyphens than the current link.

Since I don't have a ton of experience with neither Markdown nor Grav - and have no idea how to even test whether the Canada-approved section link works in Grav - I decided to just create a bug report instead. This might be an easy thing to fix, or it might be more complicated, tbh I have no idea.

Update docs on migrations

Per the comment in mautic/mautic#9709 (comment) we should update the docs to include instructions for new migrations changing schema introduced in M2 to account for the fact that it was decided that we would not introduce a migration to migrate all signed integers to unsigned because the migration would be massive.

Such migrations should check to see if the other side of the constraint is signed or not (such as the one introduced in #9544). For example, migration Version20210104171005 would need something like this (not tested)

    $categoryIdColumn =  $schema->getTable("{$this->prefix}categories")->getColumn('id');
    if ($categoryIdColumn->getUnsigned()) {
        $this->addSql("ALTER TABLE {$this->prefix}lead_lists ADD category_id INT UNSIGNED DEFAULT NULL");
    } else {
        $this->addSql("ALTER TABLE {$this->prefix}lead_lists ADD category_id INT DEFAULT NULL");
    }