In order to work upstream, Linaro tries to follow the rules of the communities themselves, which are all very different, but they all have the same principles.

This document is an attempt to describe some of those principles and how Linaro works with the communities to provide value to the members at the same time as be relevant in the communities.

The Basics

Linaro's motto is "upstream first". This basically means *anything* we
distribute has to have gone upstream somewhere accepted by the
community.

We may keep local changes for a limited period when one or more of these apply:

• We have an NDA with the company and the change is about hardware under that contract.
• The community hasn't accepted yet but is in the process of accepting.
• It's an experimental feature that we're trying to convince communities to take in.
• It's related to Linaro's own infrastructure and will never go upstream.

Apart from the last one, all changes will have a short life inside
Linaro and we should push as much as we can for those changes to go
upstream. Experiments that don't get accepted upstream should be
thrown away.

We do not have the resources to sustain internal projects for too
long, and we cannot release features that haven't gone upstream.

What is "public"

Everything that is visible to non-Linaro members is public. But not
everything that is public is upstream. Moreover, not everything that
is in an upstream repository is considered "upstream" for our
purposes.

We consider a patch to be upstream once it has successfully landed on
an upstream repository and runs little risk of being reverted or have
its behaviour severely altered. The changes must also be in either an
existing public release or in its certain way to a future release.

Everything else is public, but not upstream.

Examples:

• Upstream: changes committed to the gcc/llvm/linux trunks and stable for at least a few days.
• Upstream: changes merged into official GitHub/GitLab repositories, same as above.
• Public: branches in upstream repositories that will not (necessarily) make into a future release. This includes all "linaro-local", "linaro-dev" and feature branches.
• Public: changes merged in GitHub/GitLab forked repositories (your own or someone else's).
• Public: all changes in Linaro's Git server / GitHub repositories (unless they're the official repos).

This distinction is important, so that we don't stop once we reach
Linaro's git server or GitHub. If we stop then, the changes are not
upstream nor they will ever reach a public release of any tool, and
Linaro will *not* maintain it locally for any period of time.

Essentially, all work will be lost if it's not upstream.

Linaro Releases

In contrast to the upstream policy, Linaro releases a lot of tools
with changes that are not in upstream releases yet. But there is no
paradox, here. All those changes are in some upstream repository
(trunk or next release), and will reach an upstream release soon.

So, all patches to the kernel, toolchain, android that we submit, they
go upstream first (into trunk, usually), and then we backport them
into older / internal releases. In the same way, we backport other
people's patches, too, for our internal releases.

This means a Linaro kernel that works with a board today is guaranteed
to lead to an upstream kernel that works in the same way. Nothing is
kept exclusively inside Linaro.

Steps to upstream

There are two main ways one can work upstream while at Linaro, and
that depends on what you are doing.

If you are fixing bugs, working on trunk features or refactoring
upstream code, you *have* to work directly with the upstream
community. All patches go there first, nothing stays in Linaro for any
period of time. This is important because upstream trees change very
rapidly, and we don't have validation infrastructure to cope with all
those changes.

If you are developing a new tool, a major change or an experimental
feature, you may keep your changes local (inside Linaro's Git or
GitHub or a branch in the upstream repo). Where it lies depends on
what you're trying to do, but it *has* to be public (unless it's under
NDA).

In the second case, once it's time to send upstream, you will
invariably have to work on the patches to make them acceptable to the
project you're aiming at. Normally, that means: re-base, split/merge
patches into logical change-sets, add long and meaningful commit
messages, comments, documentation, etc.

However, you *must* be aware of the "public but not upstream" perils:

• It's not because it's public that people are looking at it
• It's not because it works that the upstream community will want it
• It's not because it's a good solution that it will interact well with the upstream plans/goals

Upstream communities are filled with stories about excellent code that
got refused because no one wanted, or it wouldn't work on other
targets, or the author didn't think about this one tiny problem that
makes his/her whole approach completely invalid.

The important take away from this is: the longer it takes for you to
go upstream, the harder it *can* be.

Developing locally

If you're developing a local tool, or a large new feature, you'll want
to keep things in our repository. But that also means you should push
your changes constantly and not keep them on your machine / company
server. Essentially, when working at Linaro, you should *not* have any
company-local repository and work directly on Linaro's one.

There are a number of benefits of doing so:
 1. It backs up your code in multiple locations (we have lots of mirrors).
 2. Other people in your group can see your work, use it, comment on
it, propose changes to it.
 3. Your tech-lead / manager can follow your progress, identify
bottlenecks, and more easily help you.
 4. You can point upstream users to it, to make them aware of your proposal.
 5. A tree that changes constantly is a good tree. No one upstream
likes code-dump (one commit tree).

These practices are the first step to a healthy team. If we are all
explicit on our work, we can see each others progress, solutions,
mistakes and we can all learn from the experience.

For example, there are typos, errors, silly changes but also a good
track of progress in this simple repo:

https://git.linaro.org/leg/hpc/ohpc-scripts.git/log/

This is perfectly fine, and it's better to see all changes as they
come, than see one dump every month.

Collaboration

As we evolve as a team, and start to interact on cross-projects
(OpenHPC, LLVM, GCC), we'll need to start using the tools that we have
at our disposal. For now, we're mainly doing separate things, and
that's fine, but soon enough, there will be a time where we'll have to
collaborate, and having a thriving local community will make that
possible.

A few tools that we'll start using soon...

Gerrit: https://review.linaro.org/

Code review tool, for proposing Linaro local patches. Can also be used
to integrate with Jenkins for pre-commit test:

Jenkins: https://ci.linaro.org/

Validation automation, can build a large number of software we have at
Linaro. For example, for LLVM or GCC changes
(https://ci.linaro.org/view/tcwg-ci/), we have jobs that will build,
test and even package a tarball for you to run further tests.

Bugzilla: https://bugs.linaro.org/

For now, we're only using Jira to track our progress, but as soon as
we start shipping tools and distributions (for example, ERP CentOS for
HPC), we'll start receiving bug reports in there.

Benchmarks: TBD

We're in talks with the toolchain team to collaborate on running
benchmarks on their and our infrastructure, to have a single and
reproducible way to track performance.

Mailing Lists

Finally, the last point is about where to post you comments / questions.

A good rule of thumb is to ask *all* questions on public mailing
lists, unless it doesn't make sense.

For example, questions about Linaro's infrastructure, roadmap
planning, conference sessions are all only meaningful to us locally,
so posting to hpc-sig-devel should be enough.

But questions about broken tools, configurations, difficulties on
using or changing source code should all go upstream, to the
respective communities' mailing lists.

Most importantly, *every* upstream effort (to send code, changes,
documentation) *must* go on the upstream mailing lists / pull request.
This is a requirement of all open source projects we work with.

Feel free to copy specific people from the group (for example, many
people at Linaro copy me on emails to the LLVM list).

But *do not* copy a Linaro -list- into an upstream mailing list. This
is known as "cross-posting" and is usually very bad form, because not
everyone in one list have access to the other list, and every reply
ends up with an error on all sides.

So, if you're going to copy people, copy them directly.