+1 -168

src/docs/contributor/bug_reports.diviner

reviewed

··· 1 1 @title Contributing Bug Reports 2 2 @group detail 3 3 4 4 - Describes how to file an effective Phabricator bug report. 5 5 - 6 6 - Level Requirements 7 7 - ================== 8 8 - 9 9 - We accept bug reports through two channels: paid support and community 10 10 - support. 11 11 - 12 12 - If you are a paying customer, use the 13 13 - [[ https://admin.phacility.com/u/support | Support Channel ]] for your account 14 14 - to report bugs. This document may help you file reports which we can resolve 15 15 - more quickly, but you do not need to read it or follow the guidelines. 16 16 - 17 17 - Other users can follow the guidelines in this document to file bug reports on 18 18 - the community forum. 19 19 - 20 20 - 21 21 - Overview 22 22 - ======== 23 23 - 24 24 - This article describes how to file an effective Phabricator bug report. 4 4 + Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports. 25 5 26 26 - The most important things to do are: 27 27 - 28 28 - - check the list of common fixes below; 29 29 - - make sure Phabricator is up to date; 30 30 - - make sure we support your setup; 31 31 - - gather debugging information; and 32 32 - - explain how to reproduce the issue. 33 33 - 34 34 - The rest of this article walks through these points in detail. 35 35 - 36 36 - For general information on contributing to Phabricator, see 37 37 - @{article:Contributor Introduction}. 38 38 - 39 39 - 40 40 - Common Fixes 41 41 - ============ 42 42 - 43 43 - Before you file a report, here are some common solutions to problems: 44 44 - 45 45 - - **Update Phabricator**: We receive a lot of bug reports about issues we have 46 46 - already fixed in HEAD. Updating often resolves issues. It is common for 47 47 - issues to be fixed in less than 24 hours, so even if you've updated recently 48 48 - you should update again. If you aren't sure how to update, see the next 49 49 - section. 50 50 - - **Update Libraries**: Make sure `arcanist/` and `phabricator/` are all up 51 51 - to date. Users often update `phabricator/` but forget to update `arcanist/`. 52 52 - When you update, make sure you update all three libraries. 53 53 - - **Restart Apache or PHP-FPM**: Phabricator uses caches which don't get 54 54 - reset until you restart Apache or PHP-FPM. After updating, make sure you 55 55 - restart. 56 56 - 57 57 - 58 58 - Update Phabricator 59 59 - ================== 60 60 - 61 61 - Before filing a bug, make sure you are up to date. We receive many bug reports 62 62 - for issues we have already fixed, and even if we haven't fixed an issue we'll 63 63 - be able to resolve it more easily if you file a report based on HEAD. (For 64 64 - example, an old stack trace may not have the right line numbers, which will 65 65 - make it more difficult for us to figure out what's going wrong.) 66 66 - 67 67 - To update Phabricator, use a script like the one described in 68 68 - @{article:Upgrading Phabricator}. 69 69 - 70 70 - **If you can not update** for some reason, please include the version of 71 71 - Phabricator you are running when you file a report. 72 72 - 73 73 - For help, see @{article:Providing Version Information}. 74 74 - 75 75 - 76 76 - Supported Issues 77 77 - ================ 78 78 - 79 79 - Before filing a bug, make sure you're filing an issue against something we 80 80 - support. 81 81 - 82 82 - **We can NOT help you with issues we can not reproduce.** It is critical that 83 83 - you explain how to reproduce the issue when filing a report. 84 84 - 85 85 - For help, see @{article:Providing Reproduction Steps}. 86 86 - 87 87 - **We do NOT support prototype applications.** If you're running into an issue 88 88 - with a prototype application, you're on your own. For more information about 89 89 - prototype applications, see @{article:User Guide: Prototype Applications}. 90 90 - 91 91 - **We do NOT support third-party packages or instructions.** If you installed 92 92 - Phabricator (or configured some aspect of it) using a third-party package or by 93 93 - following a third-party guide (like a blog post), we can not help you. 94 94 - Phabricator changes quickly and third-party information is unreliable and often 95 95 - falls out of date. Contact the maintainer of the package or guide you used, 96 96 - or reinstall following the upstream instructions. 97 97 - 98 98 - **We do NOT support custom code development or third-party libraries.** If 99 99 - you're writing an extension, you're on your own. We provide some documentation, 100 100 - but can not help you with extension or library development. If you downloaded a 101 101 - library from somewhere, contact the library maintainer. 102 102 - 103 103 - **We do NOT support bizarre environments.** If your issue is specific to an 104 104 - unusual installation environment, we generally will not help you find a 105 105 - workaround. Install Phabricator in a normal environment instead. Examples of 106 106 - unusual environments are shared hosts, nontraditional hosts (gaming consoles, 107 107 - storage appliances), and hosts with unusually tight resource constraints. The 108 108 - vast majority of users run Phabricator in normal environments (modern computers 109 109 - with root access) and these are the only environments we support. 110 110 - 111 111 - Otherwise, if you're having an issue with a supported first-party application 112 112 - and followed the upstream install instructions on a normal computer, we're happy 113 113 - to try to help. 114 114 - 115 115 - 116 116 - Getting More Information 117 117 - ======================== 118 118 - 119 119 - For some issues, there are places you can check for more information. This may 120 120 - help you resolve the issue yourself. Even if it doesn't, this information can 121 121 - help us figure out and resolve an issue. 122 122 - 123 123 - - For issues with `arc` or any other command-line script, you can get more 124 124 - details about what the script is doing by adding the `--trace` flag. 125 125 - - For issues with Phabricator, check your webserver error logs. 126 126 - - For Apache, this is often `/var/log/httpd/error.log`, or 127 127 - `/var/log/apache2/error.log` or similar. 128 128 - - For nginx, check both the nginx and php-fpm logs. 129 129 - - For issues with the UI, check the Javascript error console in your web 130 130 - browser. 131 131 - - Some other things, like daemons, have their own debug flags or 132 132 - troubleshooting steps. Check the documentation for information on 133 133 - troubleshooting. Adjusting settings or enabling debugging modes may give 134 134 - you more information about the issue. 135 135 - 136 136 - 137 137 - Reproducibility 138 138 - =============== 139 139 - 140 140 - The most important part of your report content is instructions on how to 141 141 - reproduce the issue. What did you do? If you do it again, does it still break? 142 142 - Does it depend on a specific browser? Can you reproduce the issue on a test 143 143 - instance on `admin.phabricator.com`? 144 144 - 145 145 - It is nearly impossible for us to resolve many issues if we can not reproduce 146 146 - them. We will not accept reports which do not contain the information required 147 147 - to reproduce problems. 148 148 - 149 149 - For help, see @{article:Providing Reproduction Steps}. 150 150 - 151 151 - 152 152 - File a Bug Report 153 153 - ================= 154 154 - 155 155 - If you're up to date, have collected information about the problem, and have 156 156 - the best reproduction instructions you can come up with, you're ready 157 157 - to file a report. 158 158 - 159 159 - It is **particularly critical** that you include reproduction steps. 160 160 - 161 161 - You can file a report on the community forum, here: 162 162 - 163 163 - (NOTE) https://discourse.phabricator-community.org/c/bug 164 164 - 165 165 - 166 166 - Next Steps 167 167 - ========== 168 168 - 169 169 - Continue by: 170 170 - 171 171 - - reading general support information in @{article:Support Resources}; or 172 172 - - returning to the @{article:Contributor Introduction}.

+1 -235

src/docs/contributor/contributing_code.diviner

reviewed

··· 1 1 @title Contributing Code 2 2 @group detail 3 3 4 4 - Describes how to contribute code to Phabricator. 5 5 - 6 6 - Level Requirements 7 7 - ================== 8 8 - 9 9 - To contribute to the Phabricator upstream, you must first pass a series of 10 10 - ancient trials and be invited to register an account in the ancestral 11 11 - homeland of Phabricator, here on `secure.phabricator.com`. The nature and 12 12 - location of these trials is a closely guarded secret. 13 13 - 14 14 - If you have passed these trials, this document can guide you through 15 15 - contributing code. 16 16 - 17 17 - If you have not yet passed these trials, writing code is normally not the best 18 18 - way to contribute to Phabricator. See @{article:Contributor Introduction} for 19 19 - more information. 20 20 - 21 21 - 22 22 - Overview 23 23 - ======== 24 24 - 25 25 - If you're planning to send a patch to Phabricator, this guide can help you 26 26 - through the process. The most important parts of contributing code to 27 27 - Phabricator are: 28 28 - 29 29 - - File a task with a bug report or feature request //before// you write code. 30 30 - - We rarely accept patches which we haven't discussed first. 31 31 - - We do not accept patches against prototype applications. 32 32 - - You must sign the CLA. 33 33 - - We do not accept GitHub pull requests. 34 34 - - Some alternative approaches are available if your change isn't something 35 35 - we want to bring upstream. 36 36 - 37 37 - The rest of this article describes these points in more detail, and then 38 38 - provides guidance on writing and submitting patches. 39 39 - 40 40 - If you just want to contribute some code but don't have a specific bug or 41 41 - feature in mind, see the bottom of this document for tips on finding ways to get 42 42 - started. 43 43 - 44 44 - For general information on contributing to Phabricator, see 45 45 - @{article:Contributor Introduction}. 46 46 - 47 47 - 48 48 - Coordinate First 49 49 - ================ 50 50 - 51 51 - Before sending code, you should file a task describing what you'd like to write. 52 52 - 53 53 - When you file a task, mention that you'd like to write the code to fix it. We 54 54 - can help contextualize your request or bug and guide you through writing an 55 55 - upstreamable patch, provided it's something that's upstreamable. If it isn't 56 56 - upstreamable, we can let you know what the issues are and help find another 57 57 - plan of attack. 58 58 - 59 59 - You don't have to file first (for example, if you spot a misspelling it's 60 60 - normally fine to just send a diff), but for anything even moderately complex 61 61 - you're strongly encouraged to file first and coordinate with the upstream. 62 62 - 63 63 - 64 64 - Rejecting Patches 65 65 - ================= 66 66 - 67 67 - If you send us a patch without coordinating it with us first, it will probably 68 68 - be immediately rejected, or sit in limbo for a long time and eventually be 69 69 - rejected. The reasons we do this vary from patch to patch, but some of the most 70 70 - common reasons are: 71 71 - 72 72 - **Unjustifiable Costs**: We support code in the upstream forever. Support is 73 73 - enormously expensive and takes up a huge amount of our time. The cost to support 74 74 - a change over its lifetime is often 10x or 100x or 1000x greater than the cost 75 75 - to write the first version of it. Many uncoordinated patches we receive are 76 76 - "white elephants", which would cost much more to maintain than the value they 77 77 - provide. 78 78 - 79 79 - As an author, it may look like you're giving us free work and we're rejecting it 80 80 - as too expensive, but this viewpoint doesn't align with the reality of a large 81 81 - project which is actively supported by a small, experienced team. Writing code 82 82 - is cheap; maintaining it is expensive. 83 83 - 84 84 - By coordinating with us first, you can make sure the patch is something we 85 85 - consider valuable enough to put long-term support resources behind, and that 86 86 - you're building it in a way that we're comfortable taking over. 87 87 - 88 88 - **Not a Good Fit**: Many patches aren't good fits for the upstream: they 89 89 - implement features we simply don't want. Coordinating with us first helps 90 90 - make sure we're on the same page and interested in a feature. 91 91 - 92 92 - The most common type of patch along these lines is a patch which adds new 93 93 - configuration options. We consider additional configuration options to have 94 94 - an exceptionally high lifetime support cost and are very unlikely to accept 95 95 - them. Coordinate with us first. 96 96 - 97 97 - **Not a Priority**: If you send us a patch against something which isn't a 98 98 - priority, we probably won't have time to look at it. We don't give special 99 99 - treatment to low-priority issues just because there's code written: we'd still 100 100 - be spending time on something lower-priority when we could be spending it on 101 101 - something higher-priority instead. 102 102 - 103 103 - If you coordinate with us first, you can make sure your patch is in an area 104 104 - of the codebase that we can prioritize. 105 105 - 106 106 - **Overly Ambitious Patches**: Sometimes we'll get huge patches from new 107 107 - contributors. These can have a lot of fundamental problems and require a huge 108 108 - amount of our time to review and correct. If you're interested in contributing, 109 109 - you'll have more success if you start small and learn as you go. 110 110 - 111 111 - We can help you break a large change into smaller pieces and learn how the 112 112 - codebase works as you proceed through the implementation, but only if you 113 113 - coordinate with us first. 114 114 - 115 115 - **Generality**: We often receive several feature requests which ask for similar 116 116 - features, and can come up with a general approach which covers all of the use 117 117 - cases. If you send us a patch for //your use case only//, the approach may be 118 118 - too specific. When a cleaner and more general approach is available, we usually 119 119 - prefer to pursue it. 120 120 - 121 121 - By coordinating with us first, we can make you aware of similar use cases and 122 122 - opportunities to generalize an approach. These changes are often small, but can 123 123 - have a big impact on how useful a piece of code is. 124 124 - 125 125 - **Infrastructure and Sequencing**: Sometimes patches are written against a piece 126 126 - of infrastructure with major planned changes. We don't want to accept these 127 127 - because they'll make the infrastructure changes more difficult to implement. 128 128 - 129 129 - Coordinate with us first to make sure a change doesn't need to wait on other 130 130 - pieces of infrastructure. We can help you identify technical blockers and 131 131 - possibly guide you through resolving them if you're interested. 132 132 - 133 133 - 134 134 - No Prototype Changes 135 135 - ==================== 136 136 - 137 137 - With rare exceptions, we do not accept patches for prototype applications for 138 138 - the same reasons that we don't accept feature requests or bug reports. To learn 139 139 - more about prototype applications, see 140 140 - @{article:User Guide: Prototype Applications}. 141 141 - 142 142 - 143 143 - You Must Sign the CLA 144 144 - ===================== 145 145 - 146 146 - Before we can accept source code contributions, you need to submit a 147 147 - [[ https://secure.phabricator.com/L28 | Contributor License Agreement ]]. Your 148 148 - changes can not be accepted until you sign the agreement. 149 149 - 150 150 - If you haven't signed it by the time you send changes for review, you'll be 151 151 - reminded to sign it at that time. 152 152 - 153 153 - If you're submitting work on behalf of a company (like your employer), the 154 154 - company can sign the [[ https://secure.phabricator.com/L30 | Corporate 155 155 - Contributor License Agreement ]] instead. 156 156 - 157 157 - Both agreements are substantially similar to the Apache Foundation's CLAs. They 158 158 - protect Phacility and users of Phabricator by making sure we have permission to 159 159 - distribute your changes under an open source license. 160 160 - 161 161 - 162 162 - No Pull Requests 163 163 - ================ 164 164 - 165 165 - We do not accept pull requests on GitHub: 166 166 - 167 167 - - We can not monitor who has signed CLAs on GitHub. You must sign the CLA 168 168 - to contribute, and we can't tell if you've signed it or not when you send 169 169 - us a pull request. 170 170 - - Pull requests do not get lint and unit tests run, so issues which are 171 171 - normally caught statically can slip by. 172 172 - - Phabricator is code review software, and developed using its own workflows. 173 173 - Pull requests bypass some of these workflows (for example, they will not 174 174 - trigger Herald rules to notify interested parties). 175 175 - - GitHub is not the authoritative master repository and we maintain a linear 176 176 - history, so merging pull requests is cumbersome on our end. 177 177 - - If you're comfortable enough with Phabricator to contribute to it, you 178 178 - should also be comfortable using it to submit changes. 179 179 - 180 180 - Instead of sending a pull request, use `arc diff` to create a revision on the 181 181 - upstream install. Your change will go through the normal Phabricator review 182 182 - process. 183 183 - 184 184 - (GitHub does not allow repositories to disable pull requests, which is why 185 185 - it's technically possible to submit them.) 186 186 - 187 187 - 188 188 - Alternatives 189 189 - ============ 190 190 - 191 191 - If you've written code but we're not accepting it into the upstream, some 192 192 - alternative approaches include: 193 193 - 194 194 - **Maintain a local fork.** This will require some ongoing effort to port your 195 195 - changes forward when you update, but is often very reasonable for simple 196 196 - changes. 197 197 - 198 198 - **Develop as an application.** Many parts of Phabricator's infrastructure are 199 199 - modular, and modularity is increasing over time. A lot of changes can be built 200 200 - as external modules or applications without forking Phabricator itself. There 201 201 - isn't much documentation or support for this right now, but you can look at 202 202 - how other applications are implemented, and at other third-party code that 203 203 - extends Phabricator. 204 204 - 205 205 - **Rise to prominence.** We're more willing to accept borderline changes from 206 206 - community members who are active, make multiple contributions, or have a history 207 207 - with the project. This is not carte blanche, but distinguishing yourself can 208 208 - make us feel more comfortable about supporting a change which is slightly 209 209 - outside of our comfort zone. 210 210 - 211 211 - 212 212 - Writing and Submitting Patches 213 213 - ================== 214 214 - 215 215 - To actually submit a patch, run `arc diff` in `phabricator/` or `arcanist/`. 216 216 - When executed in these directories, `arc` should automatically talk to the 217 217 - upstream install. You can add `epriestley` as a reviewer. 218 218 - 219 219 - You should read the relevant coding convention documents before you submit a 220 220 - change. If you're a new contributor, you don't need to worry about this too 221 221 - much. Just try to make your code look similar to the code around it, and we 222 222 - can help you through the details during review. 223 223 - 224 224 - - @{article:General Coding Standards} (for all languages) 225 225 - - @{article:PHP Coding Standards} (for PHP) 226 226 - - @{article:Javascript Coding Standards} (for Javascript) 227 227 - 228 228 - In general, if you're coordinating with us first, we can usually provide 229 229 - guidance on how to implement things. The other articles in this section also 230 230 - provide information on how to work in the Phabricator codebase. 231 231 - 232 232 - 233 233 - Next Steps 234 234 - ========== 235 235 - 236 236 - Continue by: 237 237 - 238 238 - - returning to the @{article:Contributor Introduction}. 4 4 + Effective June 1, 2021: Phabricator is no longer actively maintained, and no longer accepting contributions.

+1 -229

src/docs/contributor/feature_requests.diviner

reviewed

··· 1 1 @title Contributing Feature Requests 2 2 @group detail 3 3 4 4 - Describes how to file an effective Phabricator feature request. 5 5 - 6 6 - 7 7 - Level Requirements 8 8 - ================== 9 9 - 10 10 - We accept feature requests through two channels: paid support and community 11 11 - support. 12 12 - 13 13 - If you are a paying customer, use the 14 14 - [[ https://admin.phacility.com/u/support | Support Channel ]] for your account 15 15 - to request features. This document may help you frame your requests in a way 16 16 - that lets us address them more quickly, but you do not need to read it or 17 17 - follow the guidelines. 18 18 - 19 19 - Other users can file requests on the 20 20 - [[ https://phurl.io/u/discourse | community forum ]]. 21 21 - 22 22 - 23 23 - Overview 24 24 - ======== 25 25 - 26 26 - This article describes how to file an effective feature request. 27 27 - 28 28 - The most important things to do are: 29 29 - 30 30 - - understand the upstream; 31 31 - - make sure your feature makes sense in the project; 32 32 - - align your expectations around timelines and priorities; 33 33 - - describe your problem, not your solution. 34 34 - 35 35 - The rest of this article walks through these points in detail. 36 36 - 37 37 - If you have a bug report (not a feature request), see 38 38 - @{article:Contributing Bug Reports} for a more tailored guide. 39 39 - 40 40 - For general information on contributing to Phabricator, see 41 41 - @{article:Contributor Introduction}. 42 42 - 43 43 - 44 44 - Understanding the Upstream 45 45 - ========================== 46 46 - 47 47 - Before filing a feature request, it may be useful to understand how the 48 48 - upstream operates. 49 49 - 50 50 - The Phabricator upstream is [[ https://www.phacility.com | Phacility, Inc ]]. 51 51 - We maintain total control over the project and roadmap. There is no democratic 52 52 - process, voting, or community-driven decision making. This model is better 53 53 - at some things and worse at others than a more community-focused model would 54 54 - be, but it is the model we operate under. 55 55 - 56 56 - We have a cohesive vision for the project in the long term, and a general 57 57 - roadmap that extends for years into the future. While the specifics of how 58 58 - we get there are flexible, many major milestones are well-established. 59 59 - 60 60 - Although we set project direction, the community is also a critical part of 61 61 - Phabricator. We aren't all-knowing, and we rely on feedback to help us identify 62 62 - issues, guide product direction, prioritize changes, and suggest features. 63 63 - 64 64 - Feature requests are an important part of this, but we ultimately build only 65 65 - features which make sense as part of the long term plan. 66 66 - 67 67 - Since it's hard to absorb a detailed understanding of that vision, //describing 68 68 - a problem// is often more effective than //requesting a feature//. We have the 69 69 - context to develop solutions which fit into our plans, address similar use 70 70 - cases, make sense with the available infrastructure, and work within the 71 71 - boundaries of our product vision. For more details on this, see below. 72 72 - 73 73 - 74 74 - Target Audiences 75 75 - ================ 76 76 - 77 77 - Some feature requests support very unusual use cases. Although we are broadly 78 78 - inclusive of many different kinds of users and use cases, we are not trying 79 79 - to make the software all things to all users. Use cases which are far afield 80 80 - from the things the majority of users do with Phabricator often face substantial 81 81 - barriers. 82 82 - 83 83 - Phabricator is primarily targeted at software projects and organizations with 84 84 - a heavy software focus. We are most likely to design, build, and prioritize 85 85 - features which serve these organizations and projects. 86 86 - 87 87 - Phabricator is primarily targeted at software professionals and other 88 88 - professionals with adjacent responsibilities (like project management and 89 89 - operations). Particularly, we assume users are proficient computer users and 90 90 - familiar with software development concepts. We are most likely to design, build 91 91 - and prioritize features which serve these users. 92 92 - 93 93 - Phabricator is primarily targeted at professionals working in teams on full-time 94 94 - projects. Particularly, we assume most users will use the software regularly and 95 95 - are often willing to spend a little more time up front to get a more efficient 96 96 - workflow in the long run. We are most likely to design, build and prioritize 97 97 - features which serve these use cases. 98 98 - 99 99 - Phabricator is not limited to these kinds of organizations, users and use cases, 100 100 - but features which are aimed at a different group of users (like students, 101 101 - casual projects, or inexperienced computer users) may be harder to get 102 102 - upstreamed. Features aimed at very different groups of users (like wedding 103 103 - planners, book clubs, or dogs) will be much harder to get upstreamed. 104 104 - 105 105 - In many cases, a feature makes something better for all users. For example, 106 106 - suppose we fixed an issue where colorblind users had difficulty doing something. 107 107 - Dogs would benefit the most, but colorblind human users would also benefit, and 108 108 - no one would be worse off. If the benefit for core users is very small these 109 109 - kinds of features may be hard to prioritize, but there is no exceptional barrier 110 110 - to getting them upstreamed. 111 111 - 112 112 - In other cases, a feature makes something better for some users and worse for 113 113 - other users. These kinds of features face a high barrier if they make the 114 114 - software better at planning weddings and worse at reviewing code. 115 115 - 116 116 - 117 117 - Setting Expectations 118 118 - ==================== 119 119 - 120 120 - We have a lot of users and a small team. Even if your feature is something we're 121 121 - interested in and a good fit for where we want the product to go, it may take 122 122 - us a long time to get around to building it. 123 123 - 124 124 - We work full time on Phabricator, and our long-term roadmap (which we call our 125 125 - [[ https://secure.phabricator.com/w/starmap/ | Starmap ]]) has many years worth 126 126 - of work. Your feature request is competing against thousands of other requests 127 127 - for priority. 128 128 - 129 129 - In general, we try to prioritize work that will have the greatest impact on the 130 130 - most users. Many feature requests are perfectly reasonable requests, but have 131 131 - very little impact, impact only a few users, and/or are complex to develop and 132 132 - support relative to their impact. It can take us a long time to get to these. 133 133 - 134 134 - Even if your feature request is simple and has substantial impact for a large 135 135 - number of users, the size of the request queue means that it is mathematically 136 136 - unlikely to be near the top. 137 137 - 138 138 - You can find some information about how we prioritize in 139 139 - [[ https://secure.phabricator.com/w/planning/ | Planning ]]. In particular, 140 140 - we reprioritize frequently and can not accurately predict when we'll build a 141 141 - feature which isn't very near to top of the queue. 142 142 - 143 143 - As a whole, this means that the overwhelming majority of feature requests will 144 144 - sit in queue for a long time without any updates, and that we won't be able to 145 145 - give you any updates or predictions about timelines. One day, out of nowhere, 146 146 - your feature will materialize. That day may be a decade from now. You should 147 147 - have realistic expectations about this when filing a feature request. 148 148 - 149 149 - 150 150 - Describe Problems 151 151 - ================= 152 152 - 153 153 - When you file a feature request, we need you to describe the problem you're 154 154 - facing first, not just your desired solution. Describing the problem you are 155 155 - facing is the **most important part** of a feature request. 156 156 - 157 157 - Often, your problem may have a lot in common with other similar problems. If we 158 158 - understand your use case we can compare it to other use cases and sometimes find 159 159 - a more powerful or more general solution which solves several problems at once. 160 160 - 161 161 - At other times, we'll have a planned solution to the problem that might be 162 162 - different from your desired solution but accomplish the same goal. Understanding 163 163 - the root issue can let us merge and contextualize things. 164 164 - 165 165 - Sometimes there's already a way to solve your problem that might just not be 166 166 - obvious. 167 167 - 168 168 - Finally, your proposed solution may not be compatible with the direction we 169 169 - want to take the product, but we may be able to come up with another solution 170 170 - which has approximately the same effect and does fit into the product direction. 171 171 - 172 172 - If you only describe the solution and not the problem, we can't generalize, 173 173 - contextualize, merge, reframe, or offer alternative solutions or workarounds. 174 174 - 175 175 - You must describe the problem you are facing when filing a feature request. We 176 176 - will not accept feature requests which do not contextualize the request by 177 177 - describing the root problem. 178 178 - 179 179 - If you aren't sure exactly what we're after when we ask you to describe a root 180 180 - problem, you can find examples and more discussion in 181 181 - @{article:Describing Root Problems}. 182 182 - 183 183 - 184 184 - Hypotheticals 185 185 - ============= 186 186 - 187 187 - We sometimes receive hypothetical feature requests about anticipated problems 188 188 - or concerns which haven't actually occurred yet. We usually can't do much about 189 189 - these until the problems actually occur, since the context required to 190 190 - understand and properly fix the root issue won't exist. 191 191 - 192 192 - One situation where this happens is when installs are thinking about adopting 193 193 - Phabricator and trying to guess what problems users might encounter during the 194 194 - transition. More generally, this includes any request like "if users do **X**, 195 195 - they might find **Y** confusing", where no actual users have encountered 196 196 - confusion yet. 197 197 - 198 198 - These requests are necessarily missing important context, maybe including the 199 199 - answers to questions like these: 200 200 - 201 201 - - Why did users do **X**? 202 202 - - What were they trying to do? 203 203 - - What did they expect to happen? 204 204 - - How often do users do this? 205 205 - 206 206 - The answers to these questions are important in establishing that the issue is 207 207 - really a problem, figuring out the best solution for it, and prioritizing the 208 208 - issue relative to other issues. 209 209 - 210 210 - Without knowing this information, we can't be confident that we've found a good 211 211 - solution to the problem, can't know if we've actually fixed the problem, and 212 212 - can't even know if the issue was really a problem in the first place (some 213 213 - hypothetical requests describe problems which no users ever encounter). 214 214 - 215 215 - We usually can't move forward without this information. In particular, we don't 216 216 - want to spend time solving hypothetical problems which no real users will ever 217 217 - encounter: the value of those changes is zero (or negative, by making the 218 218 - product more complex without providing a benefit), but they consume development 219 219 - time which could be better spent building much more valuable features. 220 220 - 221 221 - Generally, you should wait until a problem actually occurs before filing a 222 222 - request about it. 223 223 - 224 224 - 225 225 - Next Steps 226 226 - ========== 227 227 - 228 228 - Continue by: 229 229 - 230 230 - - learning about @{article: Contributing Bug Reports}; or 231 231 - - reading general support information in @{article:Support Resources}; or 232 232 - - returning to the @{article:Contributor Introduction}. 4 4 + Effective June 1, 2021: Phabricator is no longer actively maintained, and there is no way to file a feature request.

+1 -88

src/docs/user/support.diviner

reviewed

··· 2 2 @short Support 3 3 @group intro 4 4 5 5 - Resources for reporting bugs, requesting features, and getting support. 6 6 - 7 7 - Overview 8 8 - ======== 9 9 - 10 10 - This document describes available support resources. 11 11 - 12 12 - The upstream provides free support for a narrow range of problems (primarily, 13 13 - security issues and reproducible bugs) and paid support for virtually anything. 14 14 - 15 15 - The upstream does not provide free support for general problems with installing 16 16 - or configuring Phabricator. You may be able to get some help with these 17 17 - kinds of issues from the community. 18 18 - 19 19 - 20 20 - Paid Support 21 21 - ============ 22 22 - 23 23 - If you'd like upstream support, see ((pacts)). 24 24 - 25 25 - This is the only way to request features and the only way to get guaranteed 26 26 - answers from experts quickly. 27 27 - 28 28 - 29 29 - Reporting Security Vulnerabilities 30 30 - ================================== 31 31 - 32 32 - The upstream accepts, fixes, and awards bounties for reports of material 33 33 - security issues with the software. 34 34 - 35 35 - To report security issues, see @{article:Reporting Security Vulnerabilities}. 36 36 - 37 37 - 38 38 - Reporting Bugs 39 39 - ============== 40 40 - 41 41 - The upstream will accept **reproducible** bug reports in modern, first-party 42 42 - production code running in reasonable environments. Before submitting a bug 43 43 - report you **must update** to the latest version of Phabricator. 44 44 - 45 45 - To report bugs, see @{article:Contributing Bug Reports}. 46 46 - 47 47 - 48 48 - 49 49 - Contributing 50 50 - ============ 51 51 - 52 52 - Phabricator is a very difficult project to contribute to. New contributors 53 53 - will face a high barrier to entry. 54 54 - 55 55 - If you'd like to contribute to Phabricator, start with 56 56 - @{article:Contributor Introduction}. 57 57 - 58 58 - 59 59 - 60 60 - Installation and Setup Help 61 61 - =========================== 62 62 - 63 63 - You may be able to get free help with these issues from the 64 64 - [[ https://phurl.io/u/discourse | community ]]. 65 65 - 66 66 - You can also pay us for support. See ((pacts)). 67 67 - 68 68 - 69 69 - Hosting 70 70 - ========= 71 71 - 72 72 - The upstream offers Phabricator as a hosted service at 73 73 - [[ https://phacility.com | Phacility ]]. This simplifies setting up and 74 74 - operating a Phabricator instance, and automatically gives you access to a 75 75 - broader range of upstream support services. 76 76 - 77 77 - Running this service gives us a strong financial incentive to make installing 78 78 - and operating Phabricator as difficult as possible. Blinded by greed, we toil 79 79 - endlessly to make installation a perplexing nightmare that none other than 80 80 - ourselves can hope to navigate. 81 81 - 82 82 - 83 83 - Phabricator Community 84 84 - ===================== 85 85 - 86 86 - We provide hosting for a [[ https://phurl.io/u/discourse | Discussion Forum ]] 87 87 - where admininstrators and users help and answer questions from other community 88 88 - members. 89 89 - 90 90 - Upstream developers occasionally participate, but this is mostly a user to user 91 91 - community. If you run into general problems, but are not interested in paid 92 92 - support, this is the main place to find help. 5 5 + Effective June 1, 2021: Phabricator is no longer actively supported.