Skip to content

Conversation

@adiati98
Copy link
Contributor

@adiati98 adiati98 commented Nov 27, 2025

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

@adiati98 adiati98 requested a review from a team as a code owner November 27, 2025 14:33
@adiati98 adiati98 requested review from RCheesley and favour-chibueze and removed request for a team November 27, 2025 14:33
@adiati98 adiati98 changed the title Add contributing guidelines Add contributing guidelines and update README Dec 2, 2025
Copy link
Member

@RCheesley RCheesley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@adiati98
Copy link
Contributor Author

adiati98 commented Dec 4, 2025

@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:

  1. I don't apply admonitions to notes, warnings, etc. that are part of ordered and unordered list.
  2. 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.

Screenshot 2025-12-04 104004

2. Admonition as part of ordered list

Image 1

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

Screenshot 2025-12-04 104058

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.

Screenshot 2025-12-04 104207

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.

Screenshot 2025-12-04 104118

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 and others added 6 commits December 5, 2025 11:37
Co-authored-by: Ruth Cheesley <ruth@ruthcheesley.co.uk>
Co-authored-by: Ruth Cheesley <ruth@ruthcheesley.co.uk>
Co-authored-by: Ruth Cheesley <ruth@ruthcheesley.co.uk>
Co-authored-by: Ruth Cheesley <ruth@ruthcheesley.co.uk>
Copy link
Member

@RCheesley RCheesley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few small suggestions!


If you're ready to push your changes to the remote repository and create a PR, please read the "[Push changes to the remote repository](#push-changes-to-the-remote-repository)" and "[Create a PR](#create-a-pr)" sections.
### 3. Local development
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would probs put the working locally section first then have the codespaces as an 'if you can't work locally, use this' option.

@adiati98 adiati98 requested a review from RCheesley December 17, 2025 19:40
@adiati98
Copy link
Contributor Author

adiati98 commented Dec 17, 2025

@RCheesley TIL that we can wrap one point of order list with vale and it doesn't break it as in RST. 💡

Here's the preview for this PR:
https://github.com/adiati98/test-github-markdown-for-mautic/blob/main/.github/dev-docs-with-skip-vale.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS]: Update README [DOCS]: Create a Contributing Guidelines

2 participants