Changes for page Contributing

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

<
From version < 10.1 >
edited by krokosjablik
on 2009/10/04 17:45
To version < 11.1 >
edited by krokosjablik
on 2009/10/18 16:52
>
Change comment: Document converted from syntax xwiki/1.0 to syntax xwiki/2.0

Summary

Details

Page properties
Syntax
... ... @@ -1,1 +1,1 @@
1 -XWiki 1.0
1 +XWiki 2.0
Content
... ... @@ -1,51 +1,57 @@
1 -#info("This page is being reworked now, therefore don't change here anything, see the current [Draft> Drafts.XEContribute].")
1 +{{info}}This page is being reworked now, therefore don't change here anything, see the current [[Draft>>Drafts.XEContribute]].{{/info}}
2 2  
3 +{{velocity filter="none"}}
4 +{{html clean="false" wiki="true"}}
3 3  #startfloatingbox()
4 -*Contents*
5 -#toc ("2" "3" "")
6 +**Contents**
7 +
8 +{{toc start="2" depth="3" numbered=""/}}
6 6  #endfloatingbox()
7 7  
8 -1 Contributing
11 += Contributing =
9 9  
10 10  We're always looking for contributions! Here are some ways to participate in XWiki's development:
11 -* By sending feedback to the user or dev [mailing lists>Community.MailingLists]. The feedback could be 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 helps a lot!
12 -* By answering emails from others on the [mailing lists>Community.MailingLists].
13 -* By contributing applications, code snippets, plugins in the [Code Zone>code:Main.WebHome]
14 -* By sending code patches. In that case there are a [few rules>Contributing#Coding+Rules] you need to know. For example you could start with fixing of ["Paper Cuts">Main.PaperCut], that are easy to fix.
14 +* By sending feedback to the user or dev [[mailing lists>>Community.MailingLists]]. The feedback could be 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 helps a lot!
15 +* By answering emails from others on the [[mailing lists>>Community.MailingLists]].
16 +* By contributing applications, code snippets, plugins in the [[Code Zone>>code:Main.WebHome]]
17 +* By sending code patches. In that case there are a [[few rules>>Contributing#Coding+Rules]] you need to know. For example you could start with fixing of [["Paper Cuts">>Main.PaperCut]], that are easy to fix.
15 15  * By spreading the word about XWiki (Article, Blog, Books, Talks at conferences, Discussion with colleagues, etc)!
16 -* By [translating XWiki in a given language>Contributing#HProvidingtranslationforagivenlanguage] or improving an existing translation
19 +* By [[translating XWiki in a given language>>Contributing#HProvidingtranslationforagivenlanguage]] or improving an existing translation
20 +<p/>
21 +Here's a good article summarizing [[ways to contribute to an open source project without writing code>>http://devlicio.us/blogs/krzysztof_kozmic/archive/2009/09/10/how-to-contribute-to-open-source-without-writing-a-single-line-of-code.aspx]].
17 17  
18 -Here's a good article summarizing [ways to contribute to an open source project without writing code>http://devlicio.us/blogs/krzysztof_kozmic/archive/2009/09/10/how-to-contribute-to-open-source-without-writing-a-single-line-of-code.aspx].
23 +== Strategies for answering on the XWiki lists ==
19 19  
20 -1.1 Strategies for answering on the XWiki lists
21 -
22 22  Here's a good strategy that improves the XWiki documentation on xwiki.org:
26 +
23 23  1. someone (A) asks a question on a xwiki list
24 24  1. someone (B) knows the answer
25 25  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
26 26  1. If the answer is not found on xwiki.org, then B adds it (*) and then gives a link to it in the reply to A
27 -
31 +<p/>
28 28  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
29 -
33 +<p/>
30 30  What happens otherwise is that usually people answer in the email, often giving very long and elaborate answers with lots of knowledge/wisdom in it. Then another person comes in, asks the same question and we answer again, etc. The result is:
35 +
31 31  * the xwiki.org documentation is not better
32 32  * overall as a team we are less efficient
33 -
38 +<p/>
34 34  (*) One difficult in putting the answer on xwiki.org is to find the right location where to put it. So here are a few tips:
35 -* For code snippets, add it to the [Code Zone>code:Main.WebHome]
36 -* For questions on how to use XWiki, please add it to the [Features guide>platform:Features.WebHome]
37 -* For development questions, add it to the [Developer's guide>platform:DevGuide.WebHome]
38 -* For configuration questions and administration questions, add it to the [Administration guide>platform:AdminGuide.WebHome]
39 -* For other questions, add them to the [FAQ>xwiki:FAQ.WebHome]
40 40  
41 -1.1 Documentation
42 -Not satisfied with XWiki documentation? Look at the [Documentation Guide> Community.DocGuide], how you could help.
41 +* For code snippets, add it to the [[Code Zone>>code:Main.WebHome]]
42 +* For questions on how to use XWiki, please add it to the [[Features guide>>platform:Features.WebHome]]
43 +* For development questions, add it to the [[Developer's guide>>platform:DevGuide.WebHome]]
44 +* For configuration questions and administration questions, add it to the [[Administration guide>>platform:AdminGuide.WebHome]]
45 +* For other questions, add them to the [[FAQ>>xwiki:FAQ.WebHome]]
43 43  
47 +== Documentation ==
44 44  
45 -1.1 Providing translation for a given language
49 +Not satisfied with XWiki documentation? Look at the [[Documentation Guide>>Community.DocGuide]], how you could help.
46 46  
47 -We have a [Translation Wiki>http://l10n.xwiki.org] where you can provide translations for a given language. Follow the instructions there.
51 +== Providing translation for a given language ==
48 48  
53 +We have a [[Translation Wiki>>http://l10n.xwiki.org]] where you can provide translations for a given language. Follow the instructions there.
54 +<p/>
49 49  #*
50 50  * Translate the ~~[ApplicationResources.properties>http://fisheye2.cenqua.com/browse/xwiki/xwiki-platform/core/trunk/xwiki-core/src/main/resources]~~ file into the language you want (check if such a translation doesn't already exist of course).
51 51  ** To test your <code>ApplicationResources_NNN.properties</code> file, just drop it in your <code>WEB-INF/classes</code> directory and restart your Servlet Container.
... ... @@ -52,71 +52,64 @@
52 52  * Create a [JIRA>http://jira.xwiki.org] issue and attach your translation to the issue
53 53  * Make sure your resource file only contains Unicode code points and only ASCII characters. You can use [native2ascii>http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/native2ascii.html] (part of the JDK) for transforming non ASCII chars to ASCII chars or simply use your IDE as most IDE support doing this transformation for you automatically.
54 54  *#
61 +{{/html}}
62 +{{/velocity}}
55 55  
56 56  Thanks!
57 57  
58 -1.1 Creating and submitting a patch
66 +== Creating and submitting a patch ==
59 59  
60 -#info("Make sure to read these [excellent guidelines>http://et.redhat.com/~rjones/how-to-supply-code-to-open-source-projects/] for having one's code committed in the XWiki source repository.")
68 +{{info}}Make sure to read these [[excellent guidelines>>http://et.redhat.com/~rjones/how-to-supply-code-to-open-source-projects/]] for having one's code committed in the XWiki source repository.{{/info}}
61 61  
62 -When you have either completed a [JIRA issue>http://jira.xwiki.org] or just want some feedback on the work you have done, create a patch and attach the patch to the JIRA issue in question. We have a couple of guidelines when creating patches:
70 +When you have either completed a [[JIRA issue>>http://jira.xwiki.org]] or just want some feedback on the work you have done, create a patch and attach the patch to the JIRA issue in question. We have a couple of guidelines when creating patches:
71 +
63 63  * Always create the patch from the root of the project.
64 -* Always provide a single patch and not several diff files. If you're adding new files, ~~svn add~~ them first so that they appear within the single patch file.
73 +* Always provide a single patch and not several diff files. If you're adding new files, //svn add// them first so that they appear within the single patch file.
65 65  * If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.
66 66  * Attach the patch to the JIRA issue you were working on (do not paste its content in as a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.
67 67  
68 -#info("Please make sure you tag the JIRA issue with the 'patch' keyword for better handling by the committers if that is not currently the case.")
77 +{{info}}Please make sure you tag the JIRA issue with the 'patch' keyword for better handling by the committers if that is not currently the case.{{/info}}
69 69  
70 70  An example on how to create a patch from the command line:
71 -{code}
72 -$ svn diff > XWIKI-123-something.patch
73 -{code}
74 74  
75 -If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The ~~wget~~ and ~~patch~~ commands will only be available if you are on a UNIX platform or using Cygwin on Windows.
81 +{{code}}$ svn diff > XWIKI-123-something.patch{{/code}}
76 76  
77 -{code}
78 -$ wget -O - -q <URL to the patch from JIRA> | patch -p0
79 -{code}
83 +If you are picking up an issue with a existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The //wget// and //patch// commands will only be available if you are on a UNIX platform or using Cygwin on Windows.
80 80  
81 -If the patch is in a local file {{XWIKI-123.patch}} and you want to apply that use this command:
85 +{{code}}$ wget -O - -q <URL to the patch from JIRA> | patch -p0{{/code}}
82 82  
83 -{code}
84 -$ patch -p0 < XWIKI-123.patch
85 -{code}
87 +If the patch is in a local file ~{~{XWIKI-123.patch}} and you want to apply that use this command:
86 86  
89 +{{code}}$ patch -p0 < XWIKI-123.patch{{/code}}
90 +
87 87  A couple of notes:
88 88  
89 89  * If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make it useless for us as we most likely don't have the same directory structure as you.
90 90  * Put license headers in newly created files (java classes, pom files, etc).
91 -* Make sure that you follow our [code style>CodeStyle].
95 +* Make sure that you follow our [[code style>>CodeStyle]].
92 92  
97 +== Patch acceptance criteria ==
93 93  
94 -
95 -1.1 Patch acceptance criteria
96 -
97 97  There are a number of criteria that a patch will be judged on:
98 98  
99 99  * Whether it works and does what is intended. This one is probably obvious!
100 -
101 101  * Whether it fits the spirit of the project. Some patches may be rejected as they take the project in a different direction to that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed, so if you are unsure, 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.
102 -
103 103  * Whether it contains tests. It is expected that any patches 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.
104 -
105 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 106  
107 -Above all, don't be discouraged. These are the same requirements the current [Committers>Community.Committership] should hold each other to as well.
108 -And remember, your contributions are always welcome!
106 +Above all, don't be discouraged. These are the same requirements the current [[Committers>>Community.Committership]] should hold each other to as well. And remember, your contributions are always welcome!
109 109  
110 -1.1 Coding rules
108 +== Coding rules ==
111 111  
112 112  If you submit a patch you need to follow these rules:
113 -* Put the correct [Copyright>xwiki:Main.License#HCopyright] in the files
114 -* Ensure that your code passes the [build>Community.Building]. Note that the build contains some Checkstyle checks that your code must pass.
111 +
112 +* Put the correct [[Copyright>>xwiki:Main.License#HCopyright]] in the files
113 +* Ensure that your code passes the [[build>>Community.Building]]. Note that the build contains some Checkstyle checks that your code must pass.
115 115  * Ensure that you have unit tests and/or integration tests
116 116  * Use the same code formatting as the existing code.
117 -* Create a [JIRA issue|http://jira.xwiki.org] and attach your patch to it.
118 -* Create documentation for what you have added on [xwiki.org>http://xwiki.org].
119 -* Add your name on the [Hall Of Fame>Community.HallOfFame] page.
116 +* Create a [[JIRA issue>>http://jira.xwiki.org]] and attach your patch to it.
117 +* Create documentation for what you have added on [[xwiki.org>>http://xwiki.org]].
118 +* Add your name on the [[Hall Of Fame>>Community.HallOfFame]] page.
120 120  
121 121  In addition if you plan to contribute big patches that impact existing code, we recommend discussing it on the mailing list first.
122 122  

Get Connected