-
Notifications
You must be signed in to change notification settings - Fork 126
Home
Welcome to the Dicoogle wiki! This section is used to keep guidelines and tips to software development related with Dicoogle.
Please visit the Dicoogle Learning Pack for comprehensive guides on Dicoogle usage and development.
| Name | Category | Description |
|---|---|---|
| dev | Main development Branch | Dedicated to tested functionality and new features |
| master | Main security Branch | Dedicated to critical fixes |
| release/2.X | Legacy version Branch | Dedicated to maintenance of Dicoogle v2 |
| other branches | Dedicated to the remaining development stages |
Add your contribution to a separate branch
- Branch your contributions directly from one of these branches:
-
devin the majority of cases; -
masterif contributing with a critical fix which needs to be patched upstream ahead of content merged upstream; -
release/2.Xif contributing specifically to Dicoogle v2.
-
- Prefer to follow our branch naming conventions
- Always check for pre-existing branches that might be suitable to hold your contributions
Even if you're a collaborator, do not commit your contributions directly to /dev or /master
- Always create a pull request, other peers will test and merge your contributions
We have a convention for naming branches in the original repository, which we enforce to members of UA.PT Bioinformatics or BMD Software. Each branch name is composed of the following:
category/name
The possible categories are listed below.
| Category | Description |
|---|---|
| bug | Bug fixing |
| imp | Improvement on already existing features |
| new | New features being added |
| wip | Works in progress - Big features that take long to implement and will probably hang there |
| junk | Throwaway branch, created for experiments |
| releases | Keep the oldest releases, that may be mantained, such as releases/2.5.X
|
The name should be concise, and directly represent what the branch solves.
Some examples:
bug/issue234
bug/fixeditdb
new/statistics
junk/tryingboostrap3
The following list states a small description of this project's issue labels. All collaborators are advised to rely on these definitions.
-
good first issue: used for issues that should be easy to resolve (good for undergraduates or outsiders to contribute to Dicoogle) -
bug: should be used for any anomaly present in the project -
enhancement: any improvement or optimization to existing features and code base can be labeled as an enhancement -
feature request: new features not previously established or planned can be posted with this label -
in progress: use this label on pull requests holding an incomplete solution, or for durable issues in the middle of development -
in discussion: used in issues containing a discussion on a particular feature or improvement, rather than a single well-defined proposal -
help wanted: can be used by a collaborator requesting for assistance in its resolution -
feedback-request: can be used when an issue is requesting for feedback from collaborators, containing a matter that must be answered before any other procedure related to the issue can take place -
invalid: used for issues or pull requests that propose nothing relevant or useful to the project -
wontfix: used for no-problems or other issues that should never be fixed -
duplicate: similar toinactiveorwontfix, should be used for issues already being addressed in another one (a reference to the original issue should be included before closing).
The high priority, medium priority and low priority labels are disjoint and represent how important the issue is in the project. These are not mandatory and can be applied later on by a project maintainer or the development leader.
Furthermore, we also categorize issues depending on which component the issue relates to: dicoogle-core, sdk and webapp.
Use UTF-8 character encoding for all source code. Some adjustments in your IDE of choice may be required. Although we do not enforce a particular kind of indentation, please attempt to use the same indentation as the one presented in the same file.
Please consider these additional points when working on the web application:
- Run ESLint by calling
npm run lintorgulp lint. Do not push on errors, and prefer clearing out warnings before committing. - Prefer using React Bootstrap components (package
react-bootstrap) instead of building Bootstrap elements manually. - Prefer using the new ES2015 module format for all files. (
import X from './somewhere'instead ofconst X = require('./somewhere'),export default Yinstead ofmodule.exports = Y, etc.). - If a file uses JSX, please name it with the ".jsx" extension.
- For new React components, please prefer writing them as classes or pure functions.
React.createClassorcreateReactClassis being phased out. - Use
dicoogle-clientwhen communicating with the server.
All dependencies are managed through maven. Before adding a new dependency, make sure that the functionality is not listed in the Libraries section. We wish to avoid creating superfluous dependencies.
Use slf4j for all logging purposes, rather than interfacing with java.util.logging or log4j directly. All pieces of advice regarding the use of slf4j apply (see the FAQ).
Avoid performing concatenations in the logged text. Do not write:
logger.info("Status: " + status.toString()); // DO NOT WRITE THISUse template matching instead:
logger.info("Status: {}", status); // OKDo not call toString() on the template arguments, as this is done automatically and only when needed.
Restrict ERROR level log instructions to situations where something critical occurred in the application, often associated to bugs in the software, and that should be attended by an administrator.
Few developers often have some problems to connect remote debugger and debug plugin code. Just an example, for Unix systems:
JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"
java $JAVA_OPTS -Dlog4j.configurationFile=log4j2.xml -cp "dicoogle.jar" pt.ua.dicoogle.Main -s
Now, the java debugger can be connected remotely using 5005 port. This is only one generic way that works with any Java Debugger, but there are few other ways to debug depending on the IDE.