mirror of
https://we.phorge.it/source/phorge.git
synced 2025-01-07 13:21:02 +01:00
ce7c2097b2
Summary: Fixes T9218. Fixes T8320. Fixes T8661. This isn't exhaustive but documents the stuff that cropped up in this iteration as needing documentation. In particular: - Be explicit about multiple ownership. - Explain value of having one place to update your giant regexp of a trillion paths. Test Plan: Read documentation. Reviewers: chad Reviewed By: chad Maniphest Tasks: T8320, T8661, T9218 Differential Revision: https://secure.phabricator.com/D14023
70 lines
2.3 KiB
Text
70 lines
2.3 KiB
Text
@title Owners User Guide
|
|
@group userguide
|
|
|
|
Group files in a codebase into packages and define ownership.
|
|
|
|
Overview
|
|
========
|
|
|
|
The Owners application allows you to group files in a codebase (or across
|
|
codebases) into packages. This can make it easier to reference a module or
|
|
subsystem in other applications, like Herald.
|
|
|
|
|
|
Creating a Package
|
|
==================
|
|
|
|
To create a package, choose a name and add some files which belong to the
|
|
package. For example, you might define an "iOS Application" package by
|
|
including these paths:
|
|
|
|
/conf/ios/
|
|
/src/ios/
|
|
/shared/assets/mobile/
|
|
|
|
Any files in those directories are considered to be part of the package, and
|
|
you can now conveniently refer to them (for example, in a Herald rule) by
|
|
refering to the package instead of copy/pasting a huge regular expression
|
|
into a bunch of places.
|
|
|
|
If new source files are later added, or the scope of the package otherwise
|
|
expands or contracts, you can edit the package definition to keep things
|
|
updated.
|
|
|
|
You can use "exclude" paths to ignore subdirectories which would otherwise
|
|
be considered part of the package. For example, you might exclude a path
|
|
like this:
|
|
|
|
/conf/ios/generated/
|
|
|
|
Perhaps that directory contains some generated configuration which frequently
|
|
changes, and which you aren't concerned about.
|
|
|
|
After creating a package, files the package contains will be identified as
|
|
belonging to the package when you look at them in Diffusion, or look at changes
|
|
which affect them in Diffusion or Differential.
|
|
|
|
|
|
Files in Multiple Packages
|
|
==========================
|
|
|
|
Multiple packages may own the same file. For example, both the
|
|
"Android Application" and the "iOS Application" packages might own a path
|
|
like this, containing resources used by both:
|
|
|
|
/shared/assets/mobile/
|
|
|
|
If both packages own this directory, files in the directory are considered to
|
|
be part of both packages.
|
|
|
|
Packages do not need to have claims of equal specificity to own files. For
|
|
example, if you have a "Design Assets" package which owns this path:
|
|
|
|
/shared/assets/
|
|
|
|
...it will //also// own all of the files in the `mobile/` subdirectory. In this
|
|
configuration, these files are part of three packages: "iOS Application",
|
|
"Android Application", and "Design Assets".
|
|
|
|
(You can use an "exclude" rule if you want to make a different package with a
|
|
more specific claim the owner of a file or subdirectory.)
|