Skip to content

[docs]: Updates to contribution guidelines #426

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
saehejkang wants to merge 2 commits into
base: main
Choose a base branch
from
+36 −6
Open

[docs]: Updates to contribution guidelines #426

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ccfc140
updates to contribution guidelines
saehejkang Nov 21, 2025
944eebe
resolve PR comments
saehejkang Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 52 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

Contributions to Containerization are welcomed and encouraged.

## Index

- [How you can help](#how-you-can-help)
- [New to apple/containerization?](#new-to-applecontainerization)
- [Submitting issues and pull requests](#submitting-issues-and-pull-requests)
- [New to open source?](#new-to-open-source)
- [AI contribution guidelines](#ai-contribution-guidelines)
- [Code of conduct](#code-of-conduct)

## How you can help

We would love your contributions in the form of:
Expand All @@ -14,15 +23,19 @@ We would love your contributions in the form of:

Anything else that could enhance the project!

## Submitting Issues and Pull Requests
## New to apple/containerization?

To see the current list of maintainers, please refer to the [MAINTAINERS.txt](MAINTAINERS.txt) file in the repository.

## Submitting issues and pull requests

### Issues

To file a bug or feature request, use [GitHub issues](https://github.com/apple/containerization/issues/new).

🚧 For unexpected behavior or usability limitations, detailed instructions on how to reproduce the issue are appreciated. This will greatly help the priority setting and speed at which maintainers can get to your issue.

### Pull Requests
### Pull requests
Copy link
Contributor

@realrajaryan realrajaryan Dec 11, 2025

Choose a reason for hiding this comment

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

I don't see a reason to switch away from Title Casing for the topic headers, let's revert these to how they were previously so we don't add unnecessary diff

Copy link
Author

@saehejkang saehejkang Dec 12, 2025

Choose a reason for hiding this comment

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

This update was for consistency based on what I saw in both projects (docs, readmes, etc.). I would prefer to keep these changes as they are very minimal.


We require all commits be signed with any of GitHub's supported methods, such as GPG or SSH. Information on how to set this up can be found on [GitHub's docs](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#about-commit-signature-verification).

Expand Down Expand Up @@ -55,23 +68,56 @@ We do not currently accept contributions to add editor specific additions to the
git config --global core.excludesfile ~/.gitignore
```

#### Formatting Contributions
#### Formatting contributions

Make sure your contributions are consistent with the rest of the project's formatting. You can do this using our Makefile:

```bash
make fmt
```

#### Applying License Header to New Files
#### Applying license header to new files

If you submit a contribution that adds a new file, please add the license header. You can do this using our Makefile:

```bash
make update-licenses
```

### AI Contribution Guidelines
## New to open source?

### How do I pick something to work on?

In case you don't have anything specific to work on, you could
start off by picking a [good first issue](https://github.com/apple/containerization/contribute). Before you start
working on an issue:
* Check the comments, assignees, and any references to pull requests — make sure
nobody else is actively working on it, or awaiting help or review.

* If someone is assigned to the issue or volunteered to work on it, and there
are no signs of progress or activity over at least the past month, don't
hesitate to check in with them — it might be that the person moved on.

* Leave a comment that you have started working on it.

### Getting help

Once you start working on the issue, you will inevitably end up having a lot of questions. Don't be afraid to ask for help! The codebase is large and wrapping your head around it will take time. When asking for help, prefer giving as much information as possible, while highlighting the parts that you think are important. Refer to the [New to apple/containerization?](new-to-apple/containerization) section for the appropriate maintainers to ping.

### I didn't get a response from someone. What should I do?

It's possible that you ask someone a question in a issue/pull request and
you don't get a response as quickly as you'd like. If you don't get a response
within a week, it's okay to politely ping them using an `@` mention with a
reminder. If you don't get a response for 2-3 weeks in a row, please ping
someone else.
Copy link
Contributor

@katiewasnothere katiewasnothere Dec 11, 2025

Choose a reason for hiding this comment

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

Suggested change
It's possible that you ask someone a question in a issue/pull request and
you don't get a response as quickly as you'd like. If you don't get a response
within a week, it's okay to politely ping them using an `@` mention with a
reminder. If you don't get a response for 2-3 weeks in a row, please ping
someone else.
It's possible that you ask someone a question in an issue/pull request and you don't get a response as quickly as you'd like. If you don't get a response within a week, it's okay to politely ping them using an `@` mention. If you don't get a response for 2-3 weeks in a row, please ping someone else.

Copy link
Contributor

@realrajaryan realrajaryan Dec 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

this question/bullet is redundant and too prescriptive tbh, shouldn't have to be spelled out

Copy link
Author

@saehejkang saehejkang Dec 12, 2025

Choose a reason for hiding this comment

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

I disagree. Laying out a timeline for contributors to follow when using an @, will alleviate noise in the maintainers inboxes. This can go one of two ways:

  • If a contributor is afraid to ping someone multiple times, they will know it is polite/okay to do so.
  • If a contributor tends to keep asking the same person for help, they know that they should ping someone new


### I can't finish the contribution I started. :frowning_face:

Sometimes an issue ends up bigger, harder, or more time-consuming than expected — **and that’s completely fine.**
Be sure to comment on the issue saying you’re stepping away, so that someone else is able to pick it up.

## AI contribution guidelines

We welcome thoughtful use of AI tools in your contributions to this repository. We ask that you adhere to these rules in order to preserve the project's integrity, clarity, and quality, and to respect maintainer bandwidth:

Expand All @@ -81,6 +127,6 @@ We welcome thoughtful use of AI tools in your contributions to this repository.

AI tools should be used to **enhance, not replace** the human elements that make OSS special: learning, collaboration, and community growth.

## Code of Conduct
## Code of conduct

To clarify of what is expected of our contributors and community members, the Containerization team has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities and articulates our values well. For more detail, please read the [Code of Conduct](https://github.com/apple/.github/blob/main/CODE_OF_CONDUCT.md "Code of Conduct").