Wiki source code of Contributing

Last modified by Vincent Massol on 2024/03/25 13:43

Hide last authors
Vincent Massol 21.1 1 We're always looking for contributions! Here are some ways to participate in XWiki's development:
2
Manuel Smeria 21.6 3 {{toc numbered="true"/}}
krokosjablik 10.1 4
krokosjablik 12.1 5 = Give us your Feedback =
VincentMassol 1.1 6
Ecaterina Moraru (Valica) 36.1 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!
Vincent Massol 7.2 8
Vincent Massol 49.4 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:Main.Feedback.Testimonials]]. You could also tweet it using the ###xwiki## hashtag.
Vincent Massol 32.1 10
Vincent Massol 29.1 11 = Report an issue =
12
Thomas Mortagne 35.1 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]].
Vincent Massol 29.1 14
15 == Reporting a security issue ==
16
Simon Urli 50.1 17 Check out our [[Security Policy>>Community.SecurityPolicy.WebHome]] which explains the different options for reporting vulnerabilities.
Ecaterina Moraru (Valica) 36.1 18
krokosjablik 12.1 19 = Help other users =
20
slauriere 43.2 21 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]].
krokosjablik 12.1 22
23 == Strategies for answering questions ==
24
krokosjablik 11.1 25 Here's a good strategy that improves the XWiki documentation on xwiki.org:
Vincent Massol 3.1 26
slauriere 43.2 27 1. someone (A) asks a question (on a xwiki list, forum or IRC)
Vincent Massol 3.1 28 1. someone (B) knows the answer
29 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
Vincent Massol 17.2 30 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)
Vincent Massol 3.1 31
krokosjablik 12.1 32 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
33
34 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:
35
Vincent Massol 3.1 36 * the xwiki.org documentation is not better
Manuel Leduc 81.2 37 * overall as a team we are less efficient
Vincent Massol 3.1 38
JoshuaRieken 14.2 39 = Spread the word =
40
Eduard Moraru 24.2 41 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.
krokosjablik 9.1 42
Patrick Masson 23.1 43 = Join the Community =
Patrick Masson 22.1 44
Patrick Masson 23.1 45 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]].
46
krokosjablik 12.1 47 = Testing =
krokosjablik 9.1 48
Thomas Mortagne 35.1 49 * 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]].
Vincent Massol 21.1 50 * 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.
VincentMassol 1.5 51
krokosjablik 12.1 52 = Translations =
VincentMassol 1.5 53
krokosjablik 12.1 54 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.
Vincent Massol 7.1 55
Thomas Mortagne 35.1 56 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]].
Vincent Massol 23.3 57
krokosjablik 12.1 58 = Documentation =
VincentMassol 1.5 59
Vincent Massol 19.1 60 Not satisfied with the XWiki documentation? You have 2 options:
Manuel Smeria 21.6 61
Thomas Mortagne 35.1 62 * Report what you think should be improved by [[creating a JIRA issue for it>>https://jira.xwiki.org/browse/XINFRA]]
Vincent Massol 45.1 63 * 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:
Vincent Massol 32.3 64 ** Add code snippets to the [[Snippets wiki>>snippets:Main.WebHome]]
Simon Urli 81.1 65 ** Add explanations on how to use XWiki to the related [[Features guide pages>>xwiki:Documentation.UserGuide.Features.WebHome]]
66 ** Add development explanations to the related [[Developer guide's pages>>xwiki:Documentation.DevGuide.WebHome]]
67 ** Add configuration and administration explanations to the related [[Administration guide's pages>>xwiki:Documentation.AdminGuide.WebHome]]
Vincent Massol 19.1 68 ** Add other explanations to the [[FAQ>>xwiki:FAQ.WebHome]]
VincentMassol 1.1 69
Vincent Massol 45.1 70 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.
71
Thomas Mortagne 35.1 72 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]].
Silvia Macovei 17.1 73
Vincent Massol 49.1 74 Last but not least, please follow the [[Documentation guidelines>>dev:Community.DocGuide]]!
75
Vincent Massol 21.1 76 = Contribute Code =
krokosjablik 11.1 77
Vincent Massol 43.1 78 To help you contribute code we've prepared some **[[onboarding instructions>>Onboarding.WebHome]]**.
VincentMassol 1.1 79
Vincent Massol 43.1 80 More generally there are various ways to contribute code:
81
Manuel Smeria 21.6 82 * 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]].
Vincent Massol 21.1 83 * 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.
84 * If you've fixed bugs or added new features/improvements to existing extensions or modules check the [[next section>>#existingcode]].
Manuel Smeria 21.6 85 * [[Become part of the XWiki Development Team>>Committership]]!
Vincent Massol 21.1 86
87 {{id name="existingcode"/}}
Patrick Masson 23.1 88
Vincent Massol 12.2 89 = Fixing bugs or new Features/Improvements =
LuisArias 1.7 90
Manuel Smeria 21.6 91 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]].
Denis Gervalle 18.1 92
Thomas Mortagne 35.1 93 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.
VincentMassol 1.1 94
Vincent Massol 21.1 95 == Code acceptance criteria ==
VincentMassol 1.1 96
Vincent Massol 21.1 97 There are a number of criteria that your code will be judged on:
Jean-Vincent Drean 2.1 98
VincentMassol 1.1 99 * Whether it works and does what is intended. This one is probably obvious!
Vincent Massol 21.1 100 * 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.
101 * 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.
VincentMassol 1.1 102 * 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.
103
Manuel Smeria 21.6 104 Above all, don't be discouraged. These are the same requirements the current [[Committers>>Committership]] should hold each other to as well.
105 And remember: your contributions are always welcome !
VincentMassol 1.1 106
krokosjablik 11.1 107 == Coding rules ==
VincentMassol 1.1 108
Vincent Massol 21.1 109 If you submit code you need to follow these rules:
krokosjablik 11.1 110
krokosjablik 12.1 111 * Put the correct [[Copyright>>xwiki:Main.License#HCopyright]] in the files.
Manuel Smeria 21.6 112 * Ensure that your code passes the [[build>>Building]]. {{info}}The build contains some Checkstyle checks that your code must pass.{{/info}}
Vincent Massol 48.1 113 * Ensure that you have [[unit tests and/or integration tests>>dev:Community.Testing.WebHome]].
VincentMassol 1.1 114 * Use the same code formatting as the existing code.
Vincent Massol 46.1 115 * 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}}
krokosjablik 12.1 116 * Create [[documentation>>#HDocumentation]] for what you have added.
VincentMassol 1.1 117
Vincent Massol 33.1 118 More generally you can find details in the development documentation:
Ecaterina Moraru (Valica) 36.1 119
Vincent Massol 33.1 120 * [[Development Practices>>Community.DevelopmentPractices]]
Vincent Massol 83.1 121 ** It's a good idea to use the [[XWiki Watch feature>>extensions:Extension.Notifications Application.WebHome#HWatchedEntities]] to be aware of any change to the development practices.
Vincent Massol 33.1 122 * [[Code Style>>Community.CodeStyle]]
123
Vincent Massol 21.1 124 In addition if you plan to contribute large amount of code that impact existing code, we recommend discussing it on the mailing list first.
Thomas Mortagne 24.1 125
Ecaterina Moraru (Valica) 37.1 126 = Contribute Designs =
127
128 There are various ways to contribute design related artefacts:
129
130 * You can propose new ideas/features/improvements in the [[Design>>design:Main.WebHome]] wiki
Lucas Charpentier (Sereza7) 82.1 131 * You can provide resources (graphics, fonts, icons) on our [[Media Resources>>Media]] page
Ecaterina Moraru (Valica) 37.1 132
133 You can get feedback on the proposals on the mailing lists or on the Forum.
134
Vincent Massol 49.2 135 = Financial Contribution =
136
137 Developing a production-ready and feature-rich software product such as XWiki is no small feat. It's also not free. It's not because the software is open source that it's free (a common misconception! :)). Actually, every day, some developers work on improving the XWiki software and they need to earn a living. Some of them are employed by companies (https://www.xwiki.org/xwiki/bin/view/Main/Supporters/#HCompaniessponsoringdevelopment), in which case the company is paying for their salaries. In other cases, the developers are just individuals, paying with their own time (night and weekends). Currently the majority of the development is done through companies paying some employess to work on the software (the top sponsoring company being XWiki SAS for the moment).
138
139 In order for XWiki to remain alive and maintained over time there needs to be enough financial contributions going back to the companies and individuals working on the XWiki software. There are several ways to help with this:
140
141 {{toc scope="local"/}}
142
Vincent Massol 80.1 143 Thus if you can't help by participating to the code development or other ways listed on this page, consider helping financially (either as an individual or through your company). This helps **a lot** and in turn helps you as XWiki users to keep getting exciting new features or bugs fixed. Thanks!
Vincent Massol 49.2 144
145 == Make a Donation ==
146
147 You can donate through the [[XWiki OpenCollective>>https://opencollective.com/xwiki]].
148
149 == Sponsor a Feature or Bug ==
150
151 If you see a feature missing you'd like to have or some annoying bug that you'd love to see fixed, please consider [[hiring one of the sponsoring companies to do it for you>>xwiki:Main.Support#HProfessionalSupport]]. This is helping the open source project in 2 ways:
Lucas Charpentier (Sereza7) 82.1 152
Vincent Massol 49.2 153 * A new feature will be added to the product and everyone will benefit. You'll also benefit since the maintenance of it will usually be taken over by the community.
154 * Similarly for a bug fix, the product will get better and everyone will benefit
155 * The sponsoring company will get some revenue which it will use to fund more development of the project (by definition a [[sponsoring company>>xwiki:Main.Supporters.SponsoringCompanies.WebHome]] is a company having at least one active [[core committer>>Community.Committership]] on the XWiki open source project - See the [[Governance page for more details>>Community.Governance]]).
156
157 == Take a Support Contract ==
158
159 You could take a support contract from [[one of the sponsoring companies>>xwiki:Main.Support#HProfessionalSupport]]. Even if you don't need such a contract, this is one way to really help the XWiki project as it generate revenues for that company and allow it to either pay for the developers it pays to work on the open source project or it'll allow it to hire more such devs.
160
161 {{comment}}
Eduard Moraru 27.1 162 = Sponsoring issues =
163
Vincent Massol 47.2 164 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]].
Vincent Massol 28.1 165
Vincent Massol 44.1 166 {{info}}
167 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.
Eduard Moraru 28.4 168
Vincent Massol 44.1 169 We've stopped using that since the JIRA plugin wasn't supported anymore when we upgraded the xwiki.org JIRA instance.
Eduard Moraru 28.3 170
Vincent Massol 44.1 171 {{image reference="sponsorIssue.png" width="800"/}}
172 {{/info}}
Vincent Massol 49.2 173 {{/comment}}
Vincent Massol 44.1 174
Thomas Mortagne 24.1 175 = Improve contribution process =
176
177 See [[Contributions pain points>>ContributingPainPoints]].
Vincent Massol 38.1 178
179 = Google Summer of Code =
180
Vincent Massol 39.1 181 See [[GoogleSummerOfCode.WebHome]].
Vincent Massol 38.1 182
183 = Google Code-In =
184
Vincent Massol 39.1 185 See [[GoogleCodeIn.WebHome]].

Get Connected