Contributing to Stackio

We’re happy that you’re interested in contributing to Stackio!

You can contribute to Stackio in many different ways, such as providing support to others in our support discussions on GitHub, requesting new application templates, sending PRs to fix bugs, or adding new applications.

1. Support Contributions

We mainly use the GitHub Discussions feature for support requests, and we also have a community Discord server where people can look for help.

We provide Coolify-compatible compose files and guides for open-source applications, but if you run into any issues while using compose files or guides from us, you should not create issues or support posts on Coolify’s community or GitHub. Maintainers there will redirect you to Coolify support only if the issue is related to Coolify.

Everyone should use our GitHub Discussions for help instead of GitHub Issues. Only maintainers can open issues in our repository, and they are reserved for bugs and application template requests. Maintainers will convert discussions into issues when an actionable fix or feature addition is confirmed.

Receving Support

If you are requesting support, you must provide as much information as possible about your issue so others can help you effectively. Most importantly, respect everyone, people help others voluntarily in their own time.

Please avoid pinging maintainers for attention. They will check discussions when they get some free time. You can ping a maintainer if no one has responded to your discussion for over two weeks.

Providing support

If you are offering support to others, verify the information or guide before sharing it. Most importantly, be patient and kind with others, even when they are not.

2. Application requests Contributions

Everyone should create a new discussion under “Application Requests” in our GitHub repository. Only maintainers can open issues in our repository, and those are reserved for bugs and application template requests. Maintainers will convert discussions into issues when an actionable fix or feature addition is confirmed.

The application you want to see added to Stackio must have Docker images published by the official team of that application. The application should be well maintained by its team and used by many people.

Maintainers may reject application requests without providing any reason.

3. Pull requests Contributions

Maintainers may close pull requests at their discretion without giving any reason (this applies to all pull requests).

Pull request must close an Issue or Discussion

Every pull request must close an issue or a discussion in our repository.

You can send a pull request that does not close an issue or discussion, but there is no guarantee that maintainers will review it. They might review it in a day, a week, a year, or they may close it without a review.

Pull request title formatting

Every pull request must start with a category keyword. The title must begin with one of the following:

• [core] - Changes to the codebase related to the Stackio site
• [application] - Changes to existing application pages or adding a new application
• [automation] - Changes to GitHub workflow files
• [changelog] - Changes to the changelog

AI usage disclosure

If you are using AI or receiving help from AI in the process of creating the pull request (or in any of the changes in it), you should mention this in the pull request description.

We do not dislike or oppose AI usage. However, some people submit pull requests entirely done by AI without understanding what the changes do, which wastes maintainers’ time and reduces trust in the contributor.

AI usage is perfectly fine as long as you know exactly what your pull request changes do and why each change is being made.

Test before you submit

You should test your changes thoroughly before sending the pull request. Your changes must work as expected when a maintainer tests them.

Images guidelines

Applications can have screenshots and logos, which should be included on the application’s page on Stackio.

If you are adding any image to Stackio, please follow these guidelines:

1. All images should be in .webp format.
2. Application screenshots and logos should be placed in /public/images/application/<Application-Name>.
3. Images should have meaningful names (avoid names like 1.webp, use light-mode-screenshot-1.webp instead)
4. Screenshot images should have a resolution of 1920px x 1080px, and the content should be clearly visible on all devices.
5. Application logo images should have a resolution of 512px x 512px, and they should be clearly visible in both light and dark modes.

4. Setting up development environment

1. Fork the Stackio repository to your GitHub account (guide).
2. Clone the Stackio Repository from your fork to your local machine (guide)
3. Run bun install to install all dependencies
4. Run bun dev to start the development server
5. Open http://localhost:3000 in your browser to view the Stackio site and start working on your changes.
6. Once you have finished your changes, run bun lint and then bun format (if you get any lint errors or warnings).
7. Test your changes thoroughly.

5. Codebase Structure

Folder/File Explanations

• .github/: Contains GitHub-specific configurations including workflows for CI/CD, and discussion templates.
• content/: Holds the MDX content files for the documentation site.
  • (application)/: Contains MDX files for individual application documentation and deployment guides.
  • resources/: Core documentation like contributor guidelines and deployment guides.
  • meta.json: Controls sidebar content structure
• public/: Static assets served by the application, such as images, fonts, and favicons.
• src/: The main source code directory.
  • app/: Next.js app router pages and API routes.
  • components/: Reusable React components, including UI primitives and page-specific components.
  • lib/: Utility functions and shared logic.
• Taskfile.yml defines development tasks using the Task runner (a Make alternative).

6. Sending a Pull request

1. Once you have completed development, commit your changes to your forked repository.
2. Push the changes to your GitHub account (git push)
3. Visit Stackio repository on Github
4. Click the “Pull Requests” tab and then the green “New Pull Request” button.
5. Choose your fork and branch as the compare branch.
6. Fill out the pull request details and submit it by clicking “Create Pull Request”

I have read and understood the [contributor guidelines](https://stackio.shadowarcanist.com/resources/contributor-guidelines), and agree to the terms.

FAQ