@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
Update contributor documentation
Summary:
It's fairly common for people to show up and be interested in finding easy stuff to work on. This stuff basically doesn't exist and probably never will: it doesn't make much sense to deliberately leave easy bugs broken just because someone might show up and want to fix a couple of easy bugs.
Almost all of the work that's valuable to us requires a depth or bredth of context which can't be acquired in a few hours here and there, and probably always will. I think it also always //should//, in that as long as we continue refactoring and clearing technical debt aggressively and having solid static analysis support tools, we should never have a large backlog of human-intelligence codebase tasks. The closest we've ever come were probably `pht()` and `phutil_tag()`, which both have a lot of subtleties and we mostly automated `phutil_tag()` anyway. These tasks are also //incredibly boring// to write and review.
So, accept this as a reality and realign the contributor documentation to try to deal with this case:
- Set expectations about starter tasks not existing and throwing a couple of hours at the project writing code being a hard path.
- Suggest non-code contributions which anyone can do.
- Segue into code contributions with context and suggestions.
Test Plan: Generated and read documentation.
Reviewers: btrahan, chad
Reviewed By: chad
Subscribers: epriestley
Differential Revision: https://secure.phabricator.com/D8872
+84
-17
+84
-17
src/docs/contributor/contrib_intro.diviner
+84
-17
src/docs/contributor/contrib_intro.diviner
···
3
3
4
4
Introduction to contributing to Phabricator, Arcanist and libphutil.
5
5
6
-
= You Are Awesome =
6
+
Overview
7
+
========
8
+
9
+
If you'd like to contribute to Phabricator, this document can guide you though
10
+
ways you can help improve the project.
11
+
12
+
Writing code is valuable, but often isn't the best or easiest way to contribute.
13
+
In most cases we are pretty good at fixing easy stuff quickly, so we don't have
14
+
a big pile of easy stuff sitting around waiting for new contributors.
15
+
16
+
This can make it difficult to contribute code if you only have a little bit of
17
+
time to spend since most of the work that needs to be done usually requires some
18
+
heavy lifting.
19
+
20
+
Without writing any code, learning the whole codebase, making a big time
21
+
commitment, or having to touch PHP, here are some ways you can materially
22
+
contribute to Phabricator:
23
+
24
+
- Send us an email or drop by IRC just to say "thanks". A big part of the
25
+
reason we build this software is to help people solve problems, and knowing
26
+
that our efforts are appreciated is really rewarding. You can find ways to
27
+
get in touch in @{article:Give Feedback! Get Support!}
28
+
- Recommend Phabricator to people who you think might find it useful. Our
29
+
most powerful growth channel is word of mouth, and mentioning or tweeting
30
+
about Phabricator helps the project grow. If writing a tweet sounds like
31
+
too much work, you can use one of these form tweets written by our PR
32
+
department to quickly and easily shill on our behalf. Hail corporate!
33
+
34
+
> Phabricator seems like it's pretty okay
35
+
36
+
> I am not being paid to mention Phabricator in this extemporaneous, completely organic tweet
37
+
38
+
> Phabricator is objectively the best thing. Source: I am a certified, internationally recognized expert.
39
+
40
+
- Report bugs and request features. We may not always be able to fix or build
41
+
things right away, but knowing about issues users are encountering or
42
+
features they'd like to see improves our ability to plan and prioritize.
43
+
For ways to do this, see @{article:Give Feedback! Get Support!}
44
+
- Give us feedback on planned features. Most of what we'll build in the next
45
+
6-12 months currently exists on the [[ Roadmap ]] or in Maniphest. Telling
46
+
us about use cases you have can help us build better products when the time
47
+
comes to write the code.
48
+
- Hang out in IRC, and maybe answer a question or two. IRC is a completely
49
+
legit place for serious hackers to hang out anyway, but while you're there
50
+
you might see someone ask a question that you know the answer to. Helping
51
+
them out (or pointing them to the right documentation) is a big help to us.
52
+
You can find details about the IRC channel in
53
+
@{article:Give Feedback! Get Support!}
7
54
8
-
Contributors are awesome. If you're thinking about contributing, that means
9
-
you're thinking about being awesome. That already makes you a little bit
10
-
awesome. But if you contribute you'll definitely be really, seriously awesome.
55
+
If all of this sounds nice but you really just want to write some code, that's
56
+
awesome too. The rest of this document (and the other articles in this section
57
+
of the documentation) can help you get started.
11
58
12
59
= Legal Stuff =
13
60
14
-
Before we can accept contributions, you need to submit a super fine and fancy
15
-
legal document called a Facebook Contributor License Agreement, which you can
16
-
find here:
61
+
Before we can accept source code contributions, you need to submit a super fine
62
+
and fancy legal document called a Facebook Contributor License Agreement, which
63
+
you can find here:
17
64
18
65
https://developers.facebook.com/opensource/cla
19
66
20
67
= Not Sure Where To Get Started? =
21
68
22
-
If you want to contribute but aren't sure how (or want to try submitting a small
23
-
patch before you build something bigger) you can search the Phabricator
24
-
development install for open tasks (these are pretty up-to-date) or come find
25
-
us in IRC and ask for some pointers.
69
+
Because we're usually quick to fix easy bugs and issues, we often don't have a
70
+
very good backlog of starter tasks.
71
+
72
+
You can try searching in Maniphest for tasks tagged with "Easy", which might
73
+
have something, but a lot of time this list is small and the tasks on it aren't
74
+
very fun or interesting even if they aren't technically too difficult.
75
+
76
+
In general, the best way to contribute is to come to us with a problem you
77
+
encountered or something you're interested in building, and then work with us
78
+
to find a solution to it or a plan to build it. We can help turn a hacky patch
79
+
into something that's upstreamable, and you'll get a fix or feature you want.
80
+
81
+
You can also look though the rest of the open tasks for something more
82
+
substantive that you're interested in. This will give you a better chance of
83
+
finding something that's relevant to you, but many tasks are large or blocked
84
+
by other large tasks.
85
+
86
+
If you do find something, feel free to leave a comment like "I'm interested in
87
+
working on this, is this something I could reasonably help with?". We're happy
88
+
to walk through things, break larger tasks down into more detail, provide
89
+
pointers to similar changes and the right places in the codebase to get started,
90
+
and generally figure out how to attack a problem.
91
+
92
+
You can also just come find us in IRC and ask how to get started.
26
93
27
94
= Submitting Patches =
28
95
29
96
To submit patches against libphutil, Arcanist or Phabricator, create a commit
30
-
and use ##arc## to send it for review (probably with ##epriestley## as a
31
-
reviewer):
97
+
and use `arc` to send it for review (probably with `epriestley` as a reviewer):
32
98
33
99
$ arc diff
34
100
35
-
When your change is accepted, send a pull request on GitHub. (You can also
36
-
just submit a pull request, but Differential is preferred for nontrivial
37
-
changes.)
101
+
You can also submit a pull request on GitHub, but Differential is strongly
102
+
preferred.
38
103
39
104
= Suggested Reading =
40
105
41
106
You should read the relevant coding convention documents before you submit a
42
-
change and make sure you're following the project guidelines:
107
+
change. If you're a new contributor, you don't need to worry about this too
108
+
much. Just try to make your code look similar to the code around it, and we
109
+
can help you through the details during review.
43
110
44
111
- @{article:General Coding Standards} (for all languages)
45
112
- @{article:PHP Coding Standards} (for PHP)