Something went wrong. Try again.
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462@title Projects User Guide@group userguideOrganize users and objects with projects.Overview========NOTE: This document is only partially complete.Phorge projects are flexible, general-purpose groups of objects that youcan use to organize information. Projects have some basic information likea name and an icon, and may optionally have members.For example, you can create projects to provide: - **Organization**: Create a project to represent a product or initiative, then use it to organize related work. - **Groups**: Create a project to represent a group of people (like a team), then add members of the group as project members. - **Tags**: To create a tag, just create a project without any members. Then tag anything you want. - **Access Control Lists**: Add members to a project, then restrict the visibility of objects to members of that project. See "Understanding Policies" below to understand how policies and projects interact in more detail.Understanding Policies======================An important rule to understand about projects is that **adding or removingprojects to an object never affects who can see the object**.For example, if you tag a task with a project like {nav Backend}, that does notchange who can see the task. In particular, it does not limit visibility toonly members of the "Backend" project, nor does it allow them to see it if theyotherwise could not. Likewise, removing projects does not affect visibility.If you're familiar with other software that works differently, this may beunexpected, but the rule in Phorge is simple: **adding and removingprojects never affects policies.**Note that you //can// write policy rules which restrict capabilities to membersof a specific project or set of projects, but you do this by editing anobject's policies and adding rules based on project membership, not by taggingor untagging the object with projects.To manage who can seen an object, use the object's policy controls,Spaces (see @{article:Spaces User Guide}) and Custom Forms(see @{article:User Guide: Customizing Forms}).For more details about rationale, see "Policies In Depth", below.For more details about policies in general, see @{article:Policies User Guide}.Joining Projects================Once you join a project, you become a member and will receive mail sent to theproject, like a mailing list. For example, if a project is added as asubscriber on a task or a reviewer on a revision, you will receive mail aboutthat task or revision.If you'd prefer not to receive mail sent to a project, you can go to{nav Members} and select {nav Disable Mail}. If you disable mail for a project,you will no longer receive mail sent to the project.If you can edit a project, you can also always join or add members to theproject.Watching Projects=================Watching a project allows you to closely follow all activity related to aproject.You can **watch** a project by clicking {nav Watch Project} on the projectpage. To stop watching a project, click {nav Unwatch Project}.When you watch a project, you will receive a copy of mail about any objects(like tasks or revisions) that are tagged with the project, or that the projectis a subscriber, reviewer, or auditor for. For moderately active projects, thismay be a large volume of mail.Edit Notifications==================Edit notifications are generated when project details (like the projectdescription, name, or icon) are updated, or when users join or leave projects.By default, these notifications are are only sent to the acting user. Thesenotifications are usually not very interesting, and project mail is alreadycomplicated by members and watchers.If you'd like to receive edit notifications for a project, you can write aHerald rule to keep you in the loop (see @{article:Herald User Guide}).Customizing Menus=================Projects support profile menus, which are customizable. For full details onmanaging and customizing profile menus, see @{article:Profile Menu User Guide}.Here are some examples of common ways to customize project profile menus thatmay be useful:**Link to Tasks or Repositories**: You can add a menu item for "Open Tasks" or"Active Repositories" for a project by running the search in the appropriateapplication, then adding a link to the search results to the menu.This can let you quickly jump from a project screen to related tasks,revisions, repositories, or other objects.For more details on how to use search and manage queries, see@{article:Search User Guide}.**New Task Button**: To let users easily make a new task that is tagged withthe current project, add a link to the "New Task" form with the projectprefilled, or to a custom form with appropriate defaults.For information on customizing and prefilling forms, see@{article:User Guide: Customizing Forms}.**Link to Wiki Pages**: You can add links to relevant wiki pages or otherdocumentation to the menu to make it easy to find and access. You could alsolink to a Conpherence if you have a chatroom for a project.**Link to External Resources**: You can link to external resources outsideof Phorge if you have other pages which are relevant to a project.**Set Workboard as Default**: For projects that are mostly used to organizetasks, change the default item to the workboard instead of the profile to getto the workboard view more easily.**Hide Unused Items**: If you have a project which you don't expect to havemembers or won't have a workboard, you can hide these items to streamline themenu.Subprojects and Milestones==========================IMPORTANT: This feature is only partially implemented.After creating a project, you can use the{nav icon="sitemap", name="Subprojects"} menu item to add subprojects ormilestones.**Subprojects** are projects that are contained inside the main project. Youcan use them to break large or complex groups, tags, lists, or undertakingsapart into smaller pieces.**Milestones** are a special kind of subproject for organizing tasks intoblocks of work. You can use them to implement sprints, iterations, milestones,versions, etc.Subprojects and milestones have some additional special behaviors and rules,particularly around policies and membership. See below for details.This is a brief summary of the major differences between normal projects,subprojects, parent projects, and milestones.| | Normal | Parent | Subproject | Milestone ||---|---|---|---|---|| //Members// | Yes | Union of Subprojects | Yes | Same as Parent || //Policies// | Yes | Yes | Affected by Parent | Same as Parent || //Hashtags// | Yes | Yes | Yes | Special |Subprojects===========Subprojects are full-power projects that are contained inside some parentproject. You can use them to divide a large or complex project into smallerparts.Subprojects have normal members and normal policies, but note that the policiesof the parent project affect the policies of the subproject (see "ParentProjects", below).Subprojects can have their own subprojects, milestones, or both. If asubproject has its own subprojects, it is both a subproject and a parentproject. Thus, the parent project rules apply to it, and are stronger than thesubproject rules.Subprojects can have normal workboards.The maximum subproject depth is 16. This limit is intended to grossly exceedthe depth necessary in normal usage.Objects may not be tagged with multiple projects that are ancestors ordescendants of one another. For example, a task may not be tagged with both{nav Stonework} and {nav Stonework > Masonry}.When a project tag is added that is the ancestor or descendant of one or moreexisting tags, the old tags are replaced. For example, adding{nav Stonework > Masonry} to a task tagged with {nav Stonework} will replace{nav Stonework} with the newer, more specific tag.This restriction does not apply to projects which share some common ancestorbut are not themselves mutual ancestors. For example, a task may be taggedwith both {nav Stonework > Masonry} and {nav Stonework > Sculpting}.This restriction //does// apply when the descendant is a milestone. Forexample, a task may not be tagged with both {nav Stonework} and{nav Stonework > Iteration II}.Milestones==========Milestones are simple subprojects for tracking sprints, iterations, versions,or other similar blocks of work. Milestones make it easier to create and managea large number of similar subprojects (for example: {nav Sprint 1},{nav Sprint 2}, {nav Sprint 3}, etc).Milestones can not have direct members or policies. Instead, the membershipand policies of a milestones are always the same as the milestone's parentproject. This makes large numbers of milestones more manageable when changesoccur.Milestones can not have subprojects, and can not have their own milestones.By default, Milestones do not have their own hashtags.Milestones can have normal workboards.Objects may not be tagged with two different milestones of the same parentproject. For example, a task may not be tagged with both {nav Stonework >Iteration III} and {nav Stonework > Iteration V}.When a milestone tag is added to an object which already has a tag from thesame series of milestones, the old tag is removed. For example, adding the{nav Stonework > Iteration V} tag to a task which already has the{nav Stonework > Iteration III} tag will remove the {nav Iteration III} tag.This restriction does not apply to milestones which are not part of the sameseries. For example, a task may be tagged with both{nav Stonework > Iteration V} and {nav Heraldry > Iteration IX}.Parent Projects===============When you add the first subproject to an existing project, it is converted intoa **parent project**. Parent projects have some special rules.**No Direct Members**: Parent projects can not have members of their own.Instead, all of the users who are members of any subproject count as membersof the parent project. By joining (or leaving) a subproject, a user isimplicitly added to (or removed from) all ancestors of that project.Consequently, when you add the first subproject to an existing project, all ofthe project's current members are moved to become members of the subprojectinstead. Implicitly, they will remain members of the parent project because theparent project is an ancestor of the new subproject.You can edit the project afterward to change or remove members if you want tosplit membership apart in a more granular way across multiple new subprojects.**Searching**: When you search for a parent project, results for any subprojectare returned. For example, if you search for {nav Engineering}, your query willmatch results in {nav Engineering} itself, but also subprojects like{nav Engineering > Warp Drive} and {nav Engineering > Shield Batteries}.**Policy Effects**: To view a subproject or milestone, you must be able toview the parent project. As a result, the parent project's view policy nowaffects child projects. If you restrict the visibility of the parent, you alsorestrict the visibility of the children.In contrast, permission to edit a parent project grants permission to editany subproject. If a user can edit {nav Root Project}, they can also edit{nav Root Project > Child} and {nav Root Project > Child > Sprint 3}.Policies In Depth=================As discussed above, adding and removing projects never affects who can see anobject. This is an explicit product design choice aimed at reducing thecomplexity of policy management.Phorge projects are a flexible, general-purpose, freeform tool. This is agood match for many organizational use cases, but a very poor match forpolicies. It is important that policies be predictable and rigid, because thecost of making a mistake with policies is high (inadvertent disclosure ofprivate information).In Phorge, each object (like a task) can be tagged with multiple projects.This is important in a flexible organizational tool, but is a liability in apolicy tool.If each project potentially affected visibility, it would become more difficultto predict the visibility of objects and easier to make mistakes with policies.There are different, reasonable expectations about how policies might beaffected when tagging objects with projects, but these expectations are inconflict, and different users have different expectations. For example: - if a user adds a project like {nav Backend} to a task, their intent might be to //open// the task up and share it with the "Backend" team; - if a user adds a project like {nav Security Vulnerability} to a task, their intent might be to //close// the task down and restrict it to just the security team; - if a user adds a project like {nav Easy Starter Task} to a task, their intent might be to not affect policies at all; - if a user adds {nav Secret Inner Council} to a task already tagged with {nav Security Vulnerability}, their intent might be to //open// the task to members of //either// project, or //close// the task to just members of //both// projects; - if a user adds {nav Backend} to a task already tagged with {nav Security Vulnerability}, their intent is totally unclear; - in all cases, users may be adding projects purely to organize objects without intending to affect policies.We can't distinguish between these cases without adding substantial complexity,and even if we made an attempt to navigate this it would still be verydifficult to predict the effect of tagging an object with multiplepolicy-affecting projects. Users would need to learn many rules about how thesepolicy types interacted to predict the policy effects of adding or removing aproject.Because of the implied complexity, we almost certainly could not prevent somecases where a user intends to take a purely organizational action (like addinga {nav Needs Documentation} tag) and accidentally opens a private object to awide audience. The policy system is intended to make these catastrophically badcases very difficult, and allowing projects to affect policies would make thesemistakes much easier to make.We believe the only reasonable way we could reduce ambiguity and complexity isby making project policy actions explicit and rule-based. But we already have asystem for explicit, rule-based management of policies: the policy system. Thepolicy tools are designed for policy management and aimed at making actionsexplicit and mistakes very difficult.Many of the use cases where project-based access control seems like it might bea good fit can be satisfied with Spaces instead (see @{article:Spaces UserGuide}). Spaces are explicit, unambiguous containers for groups of objects withsimilar policies.Form customization also provides a powerful tool for making many policymanagement tasks easier (see @{article:User Guide: Customizing Forms}).Archiving=========In Phorge, you can both destroy a project (dangerous) or archive it (very safe).Archiving a project (or a milestone, which is a kind of project)is very much recommended, for example, to archive a project when it stopsbeing useful, when the project reaches its deadline, or when its investor turnsout to be a scam. You might be surprised how useful it is to know whichcolleagues have worked on a certain very old archived project, which fortunatelysomebody decided to archive rather than fully destroy.The {nav icon=ban,name=Archive} action is visible to all people whocan {nav icon=pencil,name=Edit} a project. As usual in Phorge,there is a confirmation dialog.After you confirm the archival, these things will happen:- wherever the tag or its hashtag are mentioned, the corresponding badge is appropriately de-colorized or struck-through.- the archived project stops appearing in the active projects list at [ /project/query/active/ ]( /project/query/active/ )- the archived project is de-prioritized from most search results and selectors, including the top search bar, the tag pickers, etc.- the archived project is muted, and does not cause "watch" notifications.- the performer of this action is logged in the recent actions.All these consequences are reversible. You can bring a project backto life anytime using the {nav icon=check,name=Activate project} action.After archiving a project, all tagged objects, tagged tasks, etc. will beintentionally kept as-is. In particular, no special read-only policy isenforced on these tagged objects. This is in line with the above sectionabout "Policies In Depth". In fact, an object can have many tags, andif a specific team group ceases its operations, that does not mean thatothers should stop working on the same tasks, etc.In case additional hiding of information is needed, you can reduce thevisibility policy of that project. For example, the visibility policy"No One" makes the project effectively invisible to others.Mastering the visibility policies helps a lot in making sure your cleanuprequests are managed professionally and in a secure way, while still allowingfuture auditing, when needed.If you still decide against archiving a project in a recoverable way,continue to the following scary and dangerous section aboutpermanent destruction.Permanently Destroying======================Phorge is designed as a safe collaborative platform that rarelyrequires @{article:Permanently Destroying Data}.If you have read that article, and if you have done a backup, and ifyou have access to the command line, and if you still want to permanentlydestroy a project (or a milestone), these will be the consequences:- The project is destroyed permanently from the database, forever (unless you have a good backup and sufficient recovery skills).- All objects, including tasks, repositories, wiki documents, calendars, secrets, other projects, etc. to which you have set visibility restrictions involving that project (example: "visible to project members") will be broken, and everyone will be locked out of them. That means these objects will become completely invisible from the web interface and API results. You can still recover from these particular policy problems, by reading the @{article:User Guide: Unlocking Objects}.- Users that were members or watchers will lose that relationship.- Tagged items will lose that relationship, including tasks, commits, wiki documents, calendar events, repositories, etc.; these objects will simply not be associated anymore with that project tag (but will remain associated with other tags, of course).- Comments and texts mentioning the hashtag of that `#project` will no longer render that project link. You will still be able to add that hashtag to another project, to revive these links.- If the project has a workboard, that workboard will be destroyed as well (tasks in that workboard will always be kept and will remain associated with other workboards).- If the project has direct milestones, these milestones will be destroyed as well. This has sense because milestones are numbered in a linear chronological sequence, and this sequence cannot "just" be moved elsewhere. For example if we have projects {nav A > B > Milestones} and if you destroy the project "B", we cannot just move these milestones up to "A", since the parent project "A" may already have its own milestones, and we would lead to sequence conflicts. (Recall that milestones are technically projects, so consider reading this list again to understand what will happen while destroying each milestone.)- If the project has a parent project, and if that parent will end up with no other child projects, that parent can be promoted to root-project again. This means membership of the parent project will be editable again.- If the project has subprojects, all subprojects and all their descendant subprojects will climb the tree depth by one level, to fill the gap you caused. Grandchildren become children, children become parents, etc. - a real mess for family photos.- You increase the risk of something completely unexpected happening, such as the destruction of your entire datacenter by Psyduck Pokemons out of recursion control.To permanently destroy a project, you will need to execute a command like this,from the root directory of the Phorge repository on your server:```./bin/remove destroy PHID-PROJ-abcdef123456```The command needs the "PHID" code of the project.Every project has a PHID which can be retrieved in multiple ways,including the {nav icon=cog,name=Manage} menu of that project, or hoveringthe cursor on the {nav icon=flag,name=Flag For Later} feature.This command requires manual confirmation. Before proceeding,take the disclaimer seriously and read the previous section again aboutarchiving projects (safe), instead of permanently destroying them (unsafe),to hopefully change your mind.