A team using a shared library finds a small bug and knows how to fix it. The library's maintainers are busy with another release. Waiting for them to implement the fix may take longer than the work itself, but sending a merge request doesn't help much if nobody knows how contributions are reviewed or released.
Cross-team contribution works when contributors can prepare a change and maintainers can take responsibility for accepting it. That requires enough project information to get started, access appropriate to the work, and an agreement about what happens after someone opens a merge request.
Make the project understandable to someone outside the team
A project's name and description help people find it; its README should help them decide whether they've found the right one. For a shared library, that means explaining what it's intended for, whether it's actively maintained, which versions are supported, and how to contact its maintainers. Topics can help people find related projects, but they don't replace that explanation.
An internal project can be discoverable to the people who need it without being available to everyone. Visibility and membership should follow the access the work requires, particularly when a repository contains customer information or sensitive configuration. Reviewing and maintaining project access covers those choices. Making contribution easier isn't a reason to broaden access indiscriminately.
The information should lead to a team or maintained contact route, rather than depend on one person still working in the same role. A project that has been replaced should point to its successor and explain what happens to existing users.
Agree on the change before investing in it
A reproducible bug and a small fix may be ready for a merge request together. A new integration or behavior change usually benefits from a conversation first. Contributors need to know whether maintainers would accept the addition and what compatibility or support concerns they should address.
An issue can hold that discussion so the decision stays with the work. If the team reaches an agreement in a meeting or chat, a short summary of the reasoning saves the next reviewer from having to find the people who were there. A decision against a proposed approach is worth recording too, especially when another team is likely to ask the same question.
Templates can prompt for the details maintainers need: how to reproduce a bug, what a proposed change should accomplish, or how a merge request was checked. A question that reviewers never use is a candidate for removal. Project-level templates work well for a project's own contribution process; group-level templates can provide common prompts across projects.1
Provide a contribution path that doesn't depend on extra privileges
A short CONTRIBUTING.md can explain how to prepare the development environment, run relevant checks, open a merge request, and request review. It should distinguish what contributors can run locally from what CI will do for them. Someone should be able to follow it without receiving deployment credentials or becoming a project maintainer.
Regular project members may work on branches in the project. Where forking is allowed, people with read access can propose changes from a fork without receiving write access to the original repository. The project's visibility and forking restrictions still apply; a fork isn't a way around access controls.
CI needs particular attention for contributions from forks. A fork's pipeline normally runs with the fork's resources. A parent-project member can choose to run a pipeline in the parent, using the proposed branch's CI configuration and the parent's available resources. That can expose secrets before the change is merged, so the maintainer should review the submitted code and CI changes before starting it. Protected variables and runners aren't available to fork merge request pipelines, but that doesn't make every other parent-project resource safe to expose.
If the contribution needs checks the contributor can't run, the instructions should explain how maintainers arrange them. Otherwise, a failed or missing pipeline can leave both sides waiting without knowing who should act.
Make review a responsibility someone can fulfill
“Contributions welcome” creates an expectation that someone will respond. Maintainers need time for review, a backup when the usual reviewer is unavailable, and a way to tell contributors when a change can't be prioritized. It's better to set that expectation early than leave a prepared change without a reply.
Code Owners can help identify specialists for affected files.2 A general maintainer should still help contributors reach the right person, particularly when a change crosses several areas. Protected changes with independent review explains how to require review without making the process depend on an unavailable reviewer.
Review feedback should make the next action clear. If a proposed fix conflicts with the project's intended behavior, explaining that behavior helps the contributor revise it. When a reviewer requests another test, explaining which failure it should catch is more instructive than simply asking for more coverage.
Finish with something the contributing team can use
For a shared component, merging a fix and releasing it are separate events. The contributing team needs to know which version contains the change and whether they need to update their configuration. Compatibility notes and release instructions help them adopt it without another round of investigation.
Longer-term ownership should also be agreed before accepting a substantial addition. A one-time contribution doesn't automatically make its author responsible for future support, and maintainers shouldn't inherit a new integration they can't maintain. Sometimes a separate extension owned by the contributing team is the better arrangement.
The first contribution from another team is a chance to improve the process. Wherever the contributor needed private instructions, those details can become part of the guide. Wherever the change waited, the teams can decide whether the cause was missing information, a review decision, or a lack of maintainer capacity. That gives them a specific problem to improve before inviting more contributions.
Further Reading
Notes
-
Group-level description templates are available in Premium and Ultimate. Project-level issue and merge request template files are available in Free, Premium, and Ultimate. ↩
-
Code Owners is available in Premium and Ultimate. A team can document maintainer responsibilities on any tier; identifying owners in prose doesn't provide required Code Owner approvals. ↩
- Description templates explains how to provide prompts for issues and merge requests.
- Forking workflow covers contributions without write access to the original project.
- Merge request pipelines for forks explains where jobs run and what maintainers should consider before running them in the parent project.