Wiki source code of Contributing

Last modified by Vincent Massol on 2020/03/20 13:27

Show last authors
1 We're always looking for contributions! Here are some ways to participate in XWiki's development:
2
3 {{toc numbered="true"/}}
4
5 = Give us your Feedback =
6
7 Do you have a great idea? Just tell us! Send your feedback to the user or developer [[mailing lists>>MailingLists]] or in the [[XWiki Survey>>xwiki:Survey.ProductFeedback]]. The feedback could be also about something that does not work, something that could be improved, a feature you'd like to see, etc. Or simply it could be that you're a happy user. Letting us know that helps a lot!
8
9 You could also check the [[feedback we've already received>>xwiki:Main.Feedback]]. If you like XWiki, Writing a nice quote about it would be really nice too. See [[examples>>xwiki:References.Testimonials]]. You could also tweet it using the ###xwiki## hashtag.
10
11 = Report an issue =
12
13 You can report issues to the [[XWiki issue tracker>>https://jira.xwiki.org]] (you'll need to register an account there the first time). The issue tracker project to report in is usually the [[Platform project>>https://jira.xwiki.org/browse/XWIKI]].
14
15 == Reporting a security issue ==
16
17 There are 2 options:
18
19 * Create an issue in the [[Platform project>>https://jira.xwiki.org/browse/XWIKI]] and make sure to select "Confidential" in the "Security Level" field so that the issue is made private and cannot be accessed by anyone evil who would use the knowledge to hack into XWiki instances.
20 * Send a mail on the [[Security Mailing List>>dev:Community.MailingLists#HPrivateMailingLists]] if you prefer to discuss the problem instead of registering an issue (for example if you're not sure it's a real problem). Note that reporting an issue will also send a notification mail to the Committers of the project and they'll be able to reply to you too.
21
22 In general we recommend using the issue tracker since this allows the Committers to have a registered issue which they know they won't be able to forget! :)
23
24 = Help other users =
25
26 Have you gained some experience with XWiki? How about sharing your experience with others? Answer questions on the [[user forum>>Discuss]] or on [[IRC>>Community.IRC]].
27
28 == Strategies for answering questions ==
29
30 Here's a good strategy that improves the XWiki documentation on xwiki.org:
31
32 1. someone (A) asks a question (on a xwiki list, forum or IRC)
33 1. someone (B) knows the answer
34 1. B verifies that the answer can be found on xwiki.org and if so gives a link to it in the reply to A
35 1. If the answer is not found on xwiki.org, then B adds it {{{(*)}}} and in his reply to A he provides a link to the answer (see the [[Documentation>>#HDocumentation]] chapter below for some tips)
36
37 In this manner we all enrich the XWiki documentation and it'll only take marginally longer to answer questions. The next time someone asks the question again we can simply point him/her to the location on xwiki.org
38
39 What happens otherwise is that people will give very long and elaborate answers with lots of knowledge/wisdom in them. After that another person comes in, asks the same question and we answer again, etc. The results are:
40
41 * the xwiki.org documentation is not better
42 * overall as a team we are less efficient
43
44 = Spread the word =
45
46 Do you like XWiki? Spread the word about it! In any way you would prefer, like Tweets, Articles, Blogs, Books, Talks at conferences, Discussion with colleagues, etc.
47
48 = Join the Community =
49
50 Want to find others to discuss/promote XWiki use? Add yourself to the [[XWiki Users, Groups & Staff map>>https://maps.google.com/maps/ms?msid=210331808187331529022.0004f02bd076d94db85c6&msa=0]].
51
52 = Testing =
53
54 * Test new XWiki versions and report bugs in [[JIRA>>https://jira.xwiki.org]]. It's important to [[correctly report bugs>>http://www.chiark.greenend.org.uk/~~sgtatham/bugs.html]].
55 * Report Compatibility of extensions with XWiki versions. Go to the [[extension you have tested>>extensions:Main.WebHome]], edit the extension page and fill the Compatibility field.
56
57 = Translations =
58
59 Is XWiki not available in your native language? Are current translations not good enough or just not complete? By contributing to the [[Translation Wiki>>http://l10n.xwiki.org]] you can improve that.
60
61 You could also help by fixing an [[open translation-related issue>>https://jira.xwiki.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+XINFRA+AND+component+in+%28%22l10n.xwiki.org%22%29+AND+status+%3D+Open+ORDER+BY+priority+DESC]].
62
63 = Documentation =
64
65 Not satisfied with the XWiki documentation? You have 2 options:
66
67 * Report what you think should be improved by [[creating a JIRA issue for it>>https://jira.xwiki.org/browse/XINFRA]]
68 * Look at the [[Documentation>>xwiki:Documentation.WebHome]] and help us improve it. One difficulty is to find the right location for new documentation. So here are a few tips:
69 ** Add code snippets to the [[Snippets wiki>>snippets:Main.WebHome]]
70 ** Add explanations on how to use XWiki to the related [[Features guide pages>>platform:Features.WebHome]]
71 ** Add development explanations to the related [[Developer guide's pages>>platform:DevGuide.WebHome]]
72 ** Add configuration and administration explanations to the related [[Administration guide's pages>>platform:AdminGuide.WebHome]]
73 ** Add other explanations to the [[FAQ>>xwiki:FAQ.WebHome]]
74
75 And if you wish to write a new documentation page or new tutorial, feel free to do that in the [[Drafts area>>Drafts.WebHome]] and ping the devs on the [[forum>>https://forum.xwiki.org]] on using the [[chat>>Community.Chat]] when it's ready or if you have questions, and we can talk together about where to move it in the doc proper.
76
77 Not sure what to work on? Check out the [[pending documentation todos>>https://jira.xwiki.org/browse/XINFRA-80?jql=project%20%3D%20XINFRA%20AND%20component%20in%20(%22xwiki.org%22)%20AND%20status%20%3D%20Open%20ORDER%20BY%20priority%20DESC]], pick an issue and start contributing. Feel free to [[create your own todo as well>>https://jira.xwiki.org/browse/XINFRA]].
78
79 = Contribute Code =
80
81 To help you contribute code we've prepared some **[[onboarding instructions>>Onboarding.WebHome]]**.
82
83 More generally there are various ways to contribute code:
84
85 * If you've developed some XWiki Extensions (applications, macros, even some code snippets in the form of scripts) you can share them easily with others by publishing them on [[the extensions wiki>>extensions:Main.WebHome]].
86 * If you're also interested in sharing the source code we encourage you to publish the code as an [[XWiki Contrib Project>>contrib:Main.WebHome]]. This allows others to work collaboratively with you on this code and improve it and fix bugs.
87 * If you've fixed bugs or added new features/improvements to existing extensions or modules check the [[next section>>#existingcode]].
88 * [[Become part of the XWiki Development Team>>Committership]]!
89
90 {{id name="existingcode"/}}
91
92 = Fixing bugs or new Features/Improvements =
93
94 Have you fixed a boring bug or added a new feature or improved an existing one? Let us know by [[adding a pull request>>https://help.github.com/articles/creating-a-pull-request]] to our [[GitHub repository>>dev:Community.SourceRepository]].
95
96 Are you looking for a place to start? Look at our [[open issues in our Issue Tracker>>https://jira.xwiki.org]]. You can also check the [[Paper Cuts>>Main.PaperCut]] which lists some easy to fix issues.
97
98 == Code acceptance criteria ==
99
100 There are a number of criteria that your code will be judged on:
101
102 * Whether it works and does what is intended. This one is probably obvious!
103 * Whether it fits with the spirit of the project. Some code may be rejected as they take the project in a different direction from that which the current development community has chosen. This is usually discussed on an issue well before the code is contributed. So if you are unsure about submitting some code please discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.
104 * Whether it contains tests. It is expected that code relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.
105 * Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.
106
107 Above all, don't be discouraged. These are the same requirements the current [[Committers>>Committership]] should hold each other to as well.
108 And remember: your contributions are always welcome !
109
110 == Coding rules ==
111
112 If you submit code you need to follow these rules:
113
114 * Put the correct [[Copyright>>xwiki:Main.License#HCopyright]] in the files.
115 * Ensure that your code passes the [[build>>Building]]. {{info}}The build contains some Checkstyle checks that your code must pass.{{/info}}
116 * Ensure that you have [[unit tests and/or integration tests>>dev:Community.Testing.WebHome]].
117 * Use the same code formatting as the existing code.
118 * Create an issue in [[JIRA>>https://jira.xwiki.org]] or assign yourself to an existing JIRA issue and add a link to the [[GitHub Pull Request>>https://help.github.com/articles/creating-a-pull-request]]. {{info}}Please make sure you tag the JIRA issue with the **patch** keyword for better handling by the committers.{{/info}}
119 * Create [[documentation>>#HDocumentation]] for what you have added.
120
121 More generally you can find details in the development documentation:
122
123 * [[Development Practices>>Community.DevelopmentPractices]]
124 * [[Code Style>>Community.CodeStyle]]
125
126 In addition if you plan to contribute large amount of code that impact existing code, we recommend discussing it on the mailing list first.
127
128 = Contribute Designs =
129
130 There are various ways to contribute design related artefacts:
131
132 * You can propose new ideas/features/improvements in the [[Design>>design:Main.WebHome]] wiki
133 * You can provide resources (graphics, fonts, icons) on our [[Media Resources>>dev:Community.Contributing]] page
134
135 You can get feedback on the proposals on the mailing lists or on the Forum.
136
137 = Sponsoring issues =
138
139 If there are [[issues>>https://jira.xwiki.org]] you'd like to see fixed, you can vote them up and wait for some good soul to come along and fix them. The other option you have to try and speed up this process is to sponsor an issue. You can do that by contacting [[one of the companies supporting the development of XWiki>>xwiki:Main.Supporters.SponsoringCompanies.WebHome]] and sponsor them to develop the feature you need or to get [[Professional Support>>xwiki:Main.Support#HProfessionalSupport]].
140
141 {{info}}
142 At some point in the past, we were using a JIRA plugin for [[FreedomSponsors.org>>http://www.FreedomSponsors.org]] (check out their [[FAQ>>https://freedomsponsors.org/faq]] for more information on how it works). You could click on the "Sponsor This!" link on the issue itself (see screenshot below). We're using [[FreedomSponsors.org>>http://www.FreedomSponsors.org]] and you should.
143
144 We've stopped using that since the JIRA plugin wasn't supported anymore when we upgraded the xwiki.org JIRA instance.
145
146 {{image reference="sponsorIssue.png" width="800"/}}
147 {{/info}}
148
149 = Improve contribution process =
150
151 See [[Contributions pain points>>ContributingPainPoints]].
152
153 = Google Summer of Code =
154
155 See [[GoogleSummerOfCode.WebHome]].
156
157 = Google Code-In =
158
159 See [[GoogleCodeIn.WebHome]].

Get Connected