Add contributing guidelines and update README #278

adiati98 · 2025-11-27T14:33:27Z

Description

This PR holds below changes:

Added contributing guidelines to the .github folder.
Moved "Adding a code sample" section from the README to contributing guidelines.
Removed sections that are no longer needed in the README.
Added "Contributing" section to the README.

Linked issue

Closes #272
Closes #279

Screenshots or screen recordings

RCheesley

Quite a few suggestions but they should be quick to fix. Thanks for working on this @adiati98 and no rush!

RCheesley · 2025-12-03T09:20:53Z

.github/CONTRIBUTING.md

+    - [Git cherry-pick](#git-cherry-pick)
+- [Getting started](#getting-started)
+  - [1. On GitHub](#1-on-github)
+  - [2. GitHub Codespaces](#2-github-codespaces)


These need adding to the accept.txt in the singular and plural.

RCheesley · 2025-12-03T09:21:22Z

.github/CONTRIBUTING.md

+
+- When you contribute to the project for the first time, please consider checking the [good first issue](https://github.com/mautic/developer-documentation-new/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) or [help wanted](https://github.com/mautic/developer-documentation-new/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) labels.
+
+- If you wish to work on an open issue, please comment on the issue, and a maintainer will assign it to you.


Suggested change

- If you wish to work on an open issue, please comment on the issue, and a maintainer will assign it to you.

- If you wish to work on an open issue, please comment on the issue, and wait to be assigned by a maintainer.

RCheesley · 2025-12-03T09:21:48Z

.github/CONTRIBUTING.md

+
+  If an issue isn't assigned, it's assumed to be available for anyone to work on. So, ensure that you're assigned to an issue **before** beginning work to avoid conflicts.
+
+  **Note:** Please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR.


Suggested change

**Note:** Please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR.

**Note:** please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR.

Could we use an admonition here?

RCheesley · 2025-12-03T09:22:44Z

.github/CONTRIBUTING.md

+
+   ![Choose fork owner on GitHub](../assets/images/choose_fork_owner_github.png)
+
+3. Uncheck the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.


Suggested change

3. Uncheck the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.

3. Remove the check in the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.

RCheesley · 2025-12-03T09:23:13Z

.github/CONTRIBUTING.md

+
+4. Click the green 'Create fork' button at the bottom.
+
+   ![An uncheck state option to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)


Suggested change

![An uncheck state option to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)

![A check box with the removed check to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)

RCheesley · 2025-12-03T09:33:13Z

README.md

 # Mautic developer documentation (new)

-This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://mautic-developer.readthedocs.io/
+This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://devdocs.mautic.org/.


Suggested change

This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://devdocs.mautic.org/.

This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Builds take a few minutes to run before changes show on https://devdocs.mautic.org following the merging of a PR. Each PR has a GitHub Action which spins up a temporary environment for reviewing the changes.

RCheesley · 2025-12-03T09:33:58Z

README.md

@@ -1,110 +1,20 @@
 [![Documentation Status][RTD badge URL]][RTD URL] [![All Contributors](https://img.shields.io/github/all-contributors/mautic/developer-documentation-new?color=ee8449&style=flat-square)](#contributors)

 # Mautic developer documentation (new)


Suggested change

# Mautic developer documentation (new)

# Mautic developer documentation

I think we can remove the 'new' part now.

RCheesley · 2025-12-03T09:34:45Z

README.md

-This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://mautic-developer.readthedocs.io/
+This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://devdocs.mautic.org/.

 If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].


Suggested change

If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].

If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs]. This still exists because we have some changes which haven't yet been ported over to the new documentation here - if you'd like to help please check the [contribution guidelines](.github/CONTRIBUTING.md).

RCheesley · 2025-12-03T09:35:51Z

README.md

+## Contributing 🤝

-Mautic's documentation uses ``reStructuredText``, or ``.rst`` files. Luckily, there's converters available that help you convert ``.md`` to ``.rst`` files. Here's an example of ``m2r`` - this converter also converts tables into ``list-table`` directives properly.
+All kinds of contributions are encouraged. For complete information on how to contribute to the Mautic developer documentation (new) repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md).


Suggested change

All kinds of contributions are encouraged. For complete information on how to contribute to the Mautic developer documentation (new) repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md).

Mautic actively encourages all kinds of contributions. For complete information on how to contribute to the Mautic developer documentation repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md).

RCheesley · 2025-12-03T09:36:28Z

README.md

-# This creates a new file with the .rst extension:
-m2r my_markdown_file.md
-```
+All contributors are required to abide by our [Code of Conduct](https://mautic.org/code-of-conduct/).


Suggested change

All contributors are required to abide by our [Code of Conduct](https://mautic.org/code-of-conduct/).

All contributors must abide by the Mautic [Code of Conduct](https://mautic.org/code-of-conduct/).

adiati98 · 2025-12-04T10:10:26Z

@RCheesley thanks so much for the suggestion! I'll apply them soon and let you know when they're ready. 👍🏼

In the meantime, I'd like to explain why I do below details across our docs:

I don't apply admonitions to notes, warnings, etc. that are part of ordered and unordered list.
I'm using <details> and <summary> tags

Admonitions

Applying GitHub admonitions for notes, tip, or warnings as part of the list does:

Break the indentation and flow
The point above, combine with many images that we use in the guidelines, make the whole guidelines not easy to read and understand

Here are some screenshot of examples:

1. Admonition as part of unordered list

As you can see, the admonition is out of the flow.

2. Admonition as part of ordered list

Image 1

Just like the example in unordered list, the admonition is out of the flow.

Image 2

After the admonition, all instructions are still belong to point 4. But the indentation follows the admonition instead of the point. This can cause confusions.

Image 3

For this one, I indent the admonition just like we indent a paragraph that's part of a point. The indentation works great, but the admonition breaks.

The `<details>` and `<summary>` tags

I'm using these tags to create a collapsible section because these sections are meant for folks who need to troubleshoot codespaces and want to know a nice-to-know info about how to maximize free tier of Codespaces.

We can make these as sub-sections. But this will make the contributing guidelines too long.

Another solution that I can come up with is to create a new file dedicated for these tip and troubleshooting.

Testing repo

I created a test repo for your consideration: https://github.com/adiati98/test-github-markdown-for-mautic/blob/main/.github/apply-suggestions-no-html-admonitions-in-list.md.

In this repo, I applied below suggestions:

Added admonitions
Remove all HTML and make the file pure Markdown. This included removing the <details> and <summary> tags, and make them sub-sections.

Just let me know if you have better solutions or we would still apply the suggestions. TIA! ✨

adiati98 added 3 commits November 27, 2025 15:28

add contributing guidelines

cbbff3d

add images

214493c

add rebase to accept.txt

86f2a3c

adiati98 requested a review from a team as a code owner November 27, 2025 14:33

adiati98 requested review from RCheesley and favour-chibueze and removed request for a team November 27, 2025 14:33

adiati98 added 6 commits December 1, 2025 12:37

move Adding a code sample from README to contributing guidelines

cd63156

add resource in the Updating contents and UI images section

b9df0ea

clarify Adding a code sample section

9e2397b

fix: small grammars and adjust wordings

c3c72a3

remove sections from README

8045ea9

add contributing section to the README

c6550d0

adiati98 changed the title ~~Add contributing guidelines~~ Add contributing guidelines and update README Dec 2, 2025

adiati98 added 2 commits December 2, 2025 12:01

minor wording fix

ec19b66

update the Updating contents and UI images section

a387d60

RCheesley requested changes Dec 3, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add contributing guidelines and update README #278

Add contributing guidelines and update README #278

adiati98 commented Nov 27, 2025 •

edited

Loading

Uh oh!

RCheesley left a comment

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

RCheesley Dec 3, 2025

Uh oh!

adiati98 commented Dec 4, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		- When you contribute to the project for the first time, please consider checking the [good first issue](https://github.com/mautic/developer-documentation-new/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) or [help wanted](https://github.com/mautic/developer-documentation-new/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) labels.

		- If you wish to work on an open issue, please comment on the issue, and a maintainer will assign it to you.


		If an issue isn't assigned, it's assumed to be available for anyone to work on. So, ensure that you're assigned to an issue before beginning work to avoid conflicts.

		Note: Please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR.


		![Choose fork owner on GitHub](../assets/images/choose_fork_owner_github.png)

		3. Uncheck the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.

	3. Uncheck the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.
	3. Remove the check in the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches.


		4. Click the green 'Create fork' button at the bottom.

		![An uncheck state option to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)

	![An uncheck state option to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)
	![A check box with the removed check to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png)

	This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://devdocs.mautic.org/.
	This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Builds take a few minutes to run before changes show on https://devdocs.mautic.org following the merging of a PR. Each PR has a GitHub Action which spins up a temporary environment for reviewing the changes.

		@@ -1,110 +1,20 @@
		[![Documentation Status][RTD badge URL]][RTD URL] [![All Contributors](https://img.shields.io/github/all-contributors/mautic/developer-documentation-new?color=ee8449&style=flat-square)](#contributors)

		# Mautic developer documentation (new)

	# Mautic developer documentation (new)
	# Mautic developer documentation

	If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].
	If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs]. This still exists because we have some changes which haven't yet been ported over to the new documentation here - if you'd like to help please check the [contribution guidelines](.github/CONTRIBUTING.md).

	All kinds of contributions are encouraged. For complete information on how to contribute to the Mautic developer documentation (new) repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md).
	Mautic actively encourages all kinds of contributions. For complete information on how to contribute to the Mautic developer documentation repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md).

	All contributors are required to abide by our [Code of Conduct](https://mautic.org/code-of-conduct/).
	All contributors must abide by the Mautic [Code of Conduct](https://mautic.org/code-of-conduct/).

Add contributing guidelines and update README #278

Are you sure you want to change the base?

Add contributing guidelines and update README #278

Conversation

adiati98 commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Linked issue

Screenshots or screen recordings

Uh oh!

RCheesley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Admonitions

1. Admonition as part of unordered list

2. Admonition as part of ordered list

Image 1

Image 2

Image 3

The <details> and <summary> tags

Testing repo

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adiati98 commented Nov 27, 2025 •

edited

Loading

adiati98 commented Dec 4, 2025 •

edited

Loading

The `<details>` and `<summary>` tags