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.
11 kB · 256 lines
at commit 2cc898a6
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257@title Contributing Code@group detailDescribes how to contribute code to Phabricator.Overview========If you're planning to send a patch to Phabricator, this guide can help youthrough the process. The most important parts of contributing code toPhabricator are: - File a task with a bug report or feature request //before// you write code. - We rarely accept patches which we haven't discussed first. - We do not accept patches against prototype applications. - You must sign the CLA. - We do not accept GitHub pull requests. - Some alternative approaches are available if your change isn't something we want to bring upstream.The rest of this article describes these points in more detail, and thenprovides guidance on writing and submitting patches.If you just want to contribute some code but don't have a specific bug orfeature in mind, see the bottom of this document for tips on finding ways to getstarted.For general information on contributing to Phabricator, see@{article:Contributor Introduction}.Coordinate First================Before sending code, you should file a bug report or feature request describingwhat you'd like to write. For details on how to do this, see these articles: - @{article:Contributing Bug Reports} - @{article:Contributing Feature Requests}When you file a task, mention that you'd like to write the code to fix it. Wecan help contextualize your request or bug and guide you through writing anupstreamable patch, provided it's something that's upstreamable. If it isn'tupstreamable, we can let you know what the issues are and help find anotherplan of attack.You don't have to file first (for example, if you spot a misspelling it'snormally fine to just send a diff), but for anything even moderately complexyou're strongly encouraged to file first and coordinate with the upstream.Rejecting Patches=================If you send us a patch without coordinating it with us first, it will probablybe immediately rejected, or sit in limbo for a long time and eventually berejected. The reasons we do this vary from patch to patch, but some of the mostcommon reasons are:**Unjustifiable Costs**: We support code in the upstream forever. Support isenormously expensive and takes up a huge amount of our time. The cost to supporta change over its lifetime is often 10x or 100x or 1000x greater than the costto write the first version of it. Many uncoordinated patches we receive are"white elephants", which would cost much more to maintain than the value theyprovide.As an author, it may look like you're giving us free work and we're rejecting itas too expensive, but this viewpoint doesn't align with the reality of a largeproject which is actively supported by a small, experienced team. Writing codeis cheap; maintaining it is expensive.By coordinating with us first, you can make sure the patch is something weconsider valuable enough to put long-term support resources behind, and thatyou're building it in a way that we're comfortable taking over.**Not a Good Fit**: Many patches aren't good fits for the upstream: theyimplement features we simply don't want. You can find more information in@{article:Contributing Feature Requests}. Coordinating with us first helpsmake sure we're on the same page and interested in a feature.The most common type of patch along these lines is a patch which adds newconfiguration options. We consider additional configuration options to havean exceptionally high lifetime support cost and are very unlikely to acceptthem. Coordinate with us first.**Not a Priority**: If you send us a patch against something which isn't apriority, we probably won't have time to look at it. We don't give specialtreatment to low-priority issues just because there's code written: we'd stillbe spending time on something lower-priority when we could be spending it onsomething higher-priority instead.If you coordinate with us first, you can make sure your patch is in an areaof the codebase that we can prioritize.**Overly Ambitious Patches**: Sometimes we'll get huge patches from newcontributors. These can have a lot of fundamental problems and require a hugeamount of our time to review and correct. If you're interested in contributing,you'll have more success if you start small and learn as you go.We can help you break a large change into smaller pieces and learn how thecodebase works as you proceed through the implementation, but only if youcoordinate with us first.**Generality**: We often receive several feature requests which ask for similarfeatures, and can come up with a general approach which covers all of the usecases. If you send us a patch for //your use case only//, the approach may betoo specific. When a cleaner and more general approach is available, we usuallyprefer to pursue it.By coordinating with us first, we can make you aware of similar use cases andopportunities to generalize an approach. These changes are often small, but canhave a big impact on how useful a piece of code is.**Infrastructure and Sequencing**: Sometimes patches are written against a pieceof infrastructure with major planned changes. We don't want to accept thesebecause they'll make the infrastructure changes more difficult to implement.Coordinate with us first to make sure a change doesn't need to wait on otherpieces of infrastructure. We can help you identify technical blockers andpossibly guide you through resolving them if you're interested.No Prototype Changes====================With rare exceptions, we do not accept patches for prototype applications forthe same reasons that we don't accept feature requests or bug reports. To learnmore about prototype applications, see@{article:User Guide: Prototype Applications}.You Must Sign the CLA=====================Before we can accept source code contributions, you need to submit a[[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Yourchanges can not be accepted until you sign the agreement.If you haven't signed it by the time you send changes for review, you'll bereminded to sign it at that time.If you're submitting work on behalf of a company (like your employer), thecompany can sign the [[ https://secure.phabricator.com/L30 | CorporateContributor License Agreement ]] instead.Both agreements are substantially similar to the Apache Foundation's CLAs. Theyprotect Phacility and users of Phabricator by making sure we have permission todistribute your changes under an open source license.No Pull Requests================We do not accept pull requests on GitHub: - We can not monitor who has signed CLAs on GitHub. You must sign the CLA to contribute, and we can't tell if you've signed it or not when you send us a pull request. - Pull requests do not get lint and unit tests run, so issues which are normally caught statically can slip by. - Phabricator is code review software, and developed using its own workflows. Pull requests bypass some of these workflows (for example, they will not trigger Herald rules to notify interested parties). - GitHub is not the authoritative master repository and we maintain a linear history, so merging pull requests is cumbersome on our end. - If you're comfortable enough with Phabricator to contribute to it, you should also be comfortable using it to submit changes.Instead of sending a pull request, use `arc diff` to create a revision on theupstream install. Your change will go through the normal Phabricator reviewprocess.(GitHub does not allow repositories to disable pull requests, which is whyit's technically possible to submit them.)Alternatives============If you've written code but we're not accepting it into the upstream, somealternative approaches include:**Maintain a local fork.** This will require some ongoing effort to port yourchanges forward when you update, but is often very reasonable for simplechanges.**Develop as an application.** Many parts of Phabricator's infrastructure aremodular, and modularity is increasing over time. A lot of changes can be builtas external modules or applications without forking Phabricator itself. Thereisn't much documentation or support for this right now, but you can look athow other applications are implemented, and at other third-party code thatextends Phabricator.**Rise to prominence.** We're more willing to accept borderline changes fromcommunity members who are active, make multiple contributions, or have a historywith the project. This is not carte blanche, but distinguishing yourself canmake us feel more comfortable about supporting a change which is slightlyoutside of our comfort zone.Writing and Submitting Patches==================To actually submit a patch, run `arc diff` in `phabricator/`, `arcanist/`, or`libphutil/`. When executed in these directories, `arc` should automaticallytalk to the upstream install. You can add `epriestley` as a reviewer.You should read the relevant coding convention documents before you submit achange. If you're a new contributor, you don't need to worry about this toomuch. Just try to make your code look similar to the code around it, and wecan help you through the details during review. - @{article:General Coding Standards} (for all languages) - @{article:PHP Coding Standards} (for PHP) - @{article:Javascript Coding Standards} (for Javascript)In general, if you're coordinating with us first, we can usually provideguidance on how to implement things. The other articles in this section alsoprovide information on how to work in the Phabricator codebase.Not Sure Where To Get Started?==============================If you don't have a specific bug or feature in mind and just want to writesome code, you can try to find something simple to get started with.Because we're usually quick to fix easy bugs and issues, we often don't have avery good backlog of starter tasks.You can try searching in Maniphest for tasks tagged with #easy, which mighthave something, but a lot of time this list is small and the tasks on it aren'tvery fun or interesting even if they aren't technically too difficult.In general, the best way to contribute is to come to us with a problem youencountered or something you're interested in building, and then work with usto find a solution to it or a plan to build it. We can help turn a hacky patchinto something that's upstreamable, and you'll get a fix or feature you want.You can also look though the rest of the open tasks for something moresubstantive that you're interested in. This will give you a better chance offinding something that's relevant to you, but many tasks are large or blockedby other large tasks.If you do find something, feel free to leave a comment like "I'm interested inworking on this, is this something I could reasonably help with?". We're happyto walk through things, break larger tasks down into more detail, providepointers to similar changes and the right places in the codebase to get started,and generally figure out how to attack a problem.Next Steps==========Continue by: - returning to the @{article:Contributor Introduction}.