Wiki Home » Development Practices

Development Practices

Last modified by Claudio Valerio on 2012/01/11 12:25

Sankoré development follows several rules listed below. If you're a Committer or if you simply wish to contribute please take the time to read them as you're expected to follow these rules.

Copyright header in source files

All files (including configuration files) must have the following copyright statement.

For C++ files

/*
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

For XML files

<!--
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->

For Shell scripts

# --------------------------------------------------------------------
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
# ---------------------------------------------------------------------

For Bat files

REM --------------------------------------------------------------------
REM This program is free software: you can redistribute it and/or modify
REM it under the terms of the GNU General Public License as published by
REM the Free Software Foundation, either version 3 of the License, or
REM (at your option) any later version.
REM
REM This program is distributed in the hope that it will be useful,
REM but WITHOUT ANY WARRANTY; without even the implied warranty of
REM MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
REM GNU General Public License for more details.
REM
REM You should have received a copy of the GNU General Public License
REM along with this program.  If not, see <http://www.gnu.org/licenses/>.
REM ---------------------------------------------------------------------

Coding Conventions

See the Code Style page.

File encoding

The following rules must be taken into account when the need for writing non-ASCII content in the XWiki sources arises:

  • All wiki documents sources must be stored in UTF-8.
  • Other XML files should always specify their encoding in the <?xml>header, and it should be UTF-8 as often as possible.
  • All other textual resources must be stored in UTF-8, minimizing the use of non-ASCII chars.

Currently, only the XML rules are broken, but this is not a serious problem since the XML reader can detect and use the charset/encoding specified in the XML header.

JIRA Best Practices

Here are some rules on how to use JIRA for the Sankoré project.

Rule: Don't create unnecessary issues

  • If you want to know whether you should create a JIRA issue or not, ask yourself the question: "is my change going to affect any user or any extension developer in any way"? If the answer is yes then you must create a JIRA issue
  • If you're fixing something related to build then it's not mandatory to create an issue. However if you do make sure you use the special component usually labeled "Build, Infrastructure and Tests" in our JIRA projects. We're excluding issues in this category from our release notes.

Rule: Use nice user-friendly titles

When you create a JIRA issue always take the time to put a nice title for the issue. The title must be understandable by a user so don't describe the issue technically but rather in what way it affects users. For example don't say "Fix the addXXX API to return an Array List" but rather "Allow creating several pages at once".

Rule: Close issues that Sankoré committers don't plan to implement

  • We close issues that we know we won't fix (using a "Fix For" value of "Duplicate", "Incomplete", "Cannot Reproduce" or "Won't Fix"). We might not want to fix them for several reasons but one reason is that the issue is for an old Sankoré project version.
  • Leaving these issues open is not a good idea since:
    • It sends the wrong signals that we're going to fix the issue
    • The issue can still be found with a search even if closed
    • When we close it then the reporter can explain why it's so important for him/her, or not. Which we wouldn't know if we hadn't closed it
    • Contributors can reopen issues and attach a patch or just create a new issue
    • It means that for all other issues we plan to fix them at some point

Back-end Development Practices

Sankoré Application Development

Read the Creating Sankoré Apps page for details on how to write Sankoré applications.

Bug Reporting

The bug reporting system resides here.

Tags:
Created by VincentMassol on 2007/01/22 16:15

This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 3.2.1 - Documentation