This helps you use a typical inner source code repository. It assumes you have:

• Joined Flutter-Global (a private link for Flutter staff).
• Know which repository you need to work with.

Quick Start

• You are automatically added to the all-flutter-global team in Flutter-Global.
• If you have default read access to the repository the maintainers have granted inner source access to you via this team. They may also have granted default write access to allow you to contribute immediately, or you may need to request this separately.
• If you get a 404 from GitHub repository URL – it’s closed source, and you need to request access from the repository maintainers to access it at all.
• Default GitHub notification settings don’t suit Flutter-Global: in your notification settings turn off “automatically watch repositories”.
• Also make sure you have added your work email address to your GitHub email settings.
• The best source of information for a repository is the README.md, CONTRIBUTING.md and service catalogue page.
• While most GitHub open source projects use a forking workflow, this awkwardness isn’t required for Flutter-Global inner source. Request write access if necessary and use a branch instead.
• Different repositories have different contribution workflows. The repository docs should tell you what to do. Read more about common branching patterns here.

Your Permissions

All repositories in Flutter-Global are Private which means you can only view or edit them once the maintainers have granted you access. Inner source repositories are those where you have read or write access by default. The maintainers do this by granting permissions to the all-flutter-global team. Read more about the Flutter-Global access models here.

Example:

These docs are markdown in the org-site repository. This repository uses a Open Contribution access model so you have default write access via the all-flutter-global team. A simple way to tell if you have write access is whether a small “edit” pencil icon appears on the top right of the README.md on the repository homepage. The org-site repository uses the Reviewed Source branching model to ensure your contribution to the docs must be approved by the maintainers of the repository.

Standard Documentation

Usually there are 2 files in the repository to help you:

• README.md describes the purpose of the repository, who and how to contact about its content, how to use/build it and onward links to further docs.
• CONTRIBUTING.md describes how to contribute: the process, a code guide, how to verify changes, CI setup and expectations and so on.

These files may not exist in the repository you are using, but are the best place to start your search for documentation.

Access Beyond the Code

To use the code in a repository you may need to access further artefacts or resources outside GitHub. For example dependencies from a divisional Artifactory, or docs in a division’s Confluence.

Repository maintainers try to eliminate dependencies that require separate access requests in stage 1 (“Readable Source”) of inner source. However such dependencies remain common. You’ll find instructions on how to access the required systems in the repo documentation.

Who Can Help You?

The best source of information on who & how to contact if you need help is the README.md or CONTRIBUTING.md files.

Repositories may be part of a capability – a group of related repositories. Each capability has a team of experts who can help known as maintainers. These maintainers may all belong in a single delivery team (stage 2), or are members of different teams and divisions (stage 3). The capability owner leads the maintainer team.

You can lookup the capability owner and maintainers for a repository in the service catalogue. They’re busy people with many demands on their time so only have limited time to assist you. Take the time to read and follow any documented routes to seek their help (e.g. a support Slack channel).

Contribution

The README.md or CONTRIBUTING.md files in a repository explain the contribution process (if a formal one exists). If unsure – use history as a guide: check the timeline and conversation in recent pull requests. You can also simply ask the maintainers as they define this process.

You should expect:

1. Early Engagement: a way to get feedback on your intentions before you & others commit significant time to it. For example a Slack discussion thread, or creating a GitHub issue or RFC document for feedback.
2. Propose & Review: a way to share your changes with others to review them. For example raising a pull request and sharing it on a capability slack channel for review.
3. Merge & Release: a predictable timeline to test the change, merge and include it in a release so all users (including you as the contributor) can get the value from the improvement.

A common mistake is to jump straight into the work itself (2). Expert feedback (1) often avoids wasted effort, and the complexities/dependencies of test & release (3) shouldn’t be under-estimated and are best understood in advance.

Whatever the required contribution process, you need write access to the repository to make a contribution. You may need to request this as part of (1) unless the repository is already Open Contribution access.