<!DOCTYPE html>
<html>
<head>
<title>OSP Documentation</title>
<link rel="stylesheet" type="text/css" href="docs_style.css">
</head>
<body>
<header class="site-header">
<div class="grid-container">
<div class="branding">
<h1><a id="header-logo" title="Homepage | opensourceprojects.eu" href="/">Open Source Projects Europe</a></h1>
</div>
</div>
</header>
<main id="page-body" class="page-container">
<div id="content_base" class="text-page documentation-page">
<h1>Quick Start Guide</h1>
<div class="content-menu">
<ul class="menu">
<li><a href="#account">Setting up your account</a></li>
<li><a href="#management">Project Management</a></li>
<li><a href="#git">Git</a></li>
<li><a href="#svn">SVN</a></li>
<li><a href="#issues">Issue Tracker</a></li>
<li><a href="#wiki">Wiki</a></li>
<li><a href="#forum">Discussion Forums</a></li>
<li><a href="#blog">Blog</a></li>
<li><a href="#faq">FAQ</a></li>
<li><a href="compass/index.html">Compass App</a></li>
</ul>
</div>
<section id="account" class="subject">
<h2>Setting up your Account</h2>
<img src="img/account.png"/>
<p>
To start using the platform you require a user account. You can create one
from the front page. Fill in your preferred display name, user name and
email address. You will soon receive an email with activation link and
your password. Activate your account by clicking the link and following
the instructions given. Now you can start working on the platform.
</p>
<p>
To login with your existing account, click the top left corner
login-link and insert your username and password.
</p>
<p>You can change your profile���s settings from the <b>Settings</b>
option on top menu. On the User Settings page you, the user, are able
to set or change several personal details. A part on this page is
reserved for user contact details, like email, Skype, and social media
contacts. You can also give the URL to your personal website, if you
have one.</p>
<img src="img/settings.png"/>
<p>
The user settings page also gives you a single-page to manage your
subscriptions. These are the items for which the platform will send you
an email notification when an update happens. You are automatically
subscribed to the content you create, but you can subscribe to individual
content or even entire tools.
</p>
<p>Choosing <b>Profile</b> from the top bar menu you get to see your newly
created public profile. It shows your projects, personal data you have
entered, skills, and email address you logged in with.</p>
</section>
<section id="management" class="subject">
<h2>Project Management</h2>
<p>You can create new projects from the projects list (from the top menu under <b>Projects</b>)
This opens a list of projects available to you. To create one of your
own, click the <b>Add a Project</b> button from the left side menu.
This opens the project creation page.
</p>
<img src="img/createproject.png" class="narrow"/>
<p>
From this page you can select the name of the project, and some of the initial project settings:
</p>
<ul>
<li>Project Name(3-15 characters long</li>
<li>Project URL name, http://opensourceproject.eu/p/<b>url-name</b></li>
<li>The tools that will be enabled for this project</li>
<li>Whether the project is private or not</li>
</ul>
<p>
With exception to the project name/url all these settings can be added at a later time. After creating you new project, you will be redirected to the project administration page.
</p>
<h3>Installing new Tools</h3>
<p>
You can install new tools in your project from the <b>Admin/ Tools</b>
and clicking on the tool you want to install. The new instance will
need a Label (that shows up in the sidebar), and a Mount point (a path
in the URL)
</p>
<p>
After installing a new tool instance, new configuration options for that instance
will be available in the same page. Multiple instances can be created, for the same type of tools.
</p>
<img src="img/itickets.png"/>
<h3>Creating subprojects</h3>
<p>
Sub projects are a common part of large projects that require
maintaining several tools and source code under a common group, such as
an ICT project. You can create sub-projects under the <b>Admin/ Tools</b>
selection.
</p>
<p>
You will be given two choices to create a sub-project: associate a sibling
project or create a new project as sub-project of the main one.
To achieve either of available options, it is necessary to navigate to
the main project's tools page
</p>
<p class="hint">Admin > Tools</p>
<p>and click to add a new Subproject tool. A form will pop up for you
to fill in the sub-project's information, such as its Label and its
Mount Point. The platform checks if the mount point already exists and
either associates the existing point as the main one, or creates a new
project with the specified title in Label and URL name. This
information is saved with the save button.</p>
<p>After the pop-up window is dismissed, the new Subproject tool will
be listed along with the other installed tools.</p>
<h3>Permissions and access control</h3>
<p>The key part of enforcing access control for a project takes place in the User Permissions page, at</p>
<p class="hint">Admin > User Permissions</p>
<p>
This page allows the project manager to define which users can read,
write or update the project's contents. Permissions are assigned by user groups.
Each project is created with an Admin, Developers, and Member.
But new user groups can be defined to further extend the control.
</p>
<img src="img/perm.png"/>
<p>The various tools in the platform inherit the general project
permissions, however some tools provide even more detailed access
control settings, enforcing per tool or per content access control.</p>
</section>
<section id="git" class="subject">
<h2>Git</h2>
<p>
GIT can be enabled enabled as a project tool in the <b>Admin > Tools</b>
page. Once added, a new entry will appear on the project sidebar.
After adding the Git tool, a new repository will be available for you project (check http://git-scm.com/ for update documentation on Git).</p>
<p>The standard way to modify the contents of your repository is using
a Git client as detailed in the Git User's Manual. If the code
repository is empty, the code browser will display some instructions to
help make the first commit and push, such as:</p>
<pre class="hint">
cd myproject
git init
# add all your files. You can use specific filenames or directories instead of '.'
git add .
git commit -a -m 'Initial commit'
git remote add origin http://user@opensourceprojects.eu/git/p/newproject/code-0
git push origin master
git branch --set-upstream master origin/master # so 'git pull' will work later
</pre>
<p>Or If using Git with an existing repository:</p>
<pre class="hint">
cd myproject
git remote add origin http://user@opensourceprojects.eu/git/p/newproject/code-0
git push origin master
git branch --set-upstream master origin/master # so 'git pull' will work later
</pre>
<p>To manage the Git tool, go to Tools page under</p>
<p class="hint">
Projects > ProjectName > Tools > Code
</p>
<p>and choose an option within the available from Git tool's block. It
allows the administrators to set visible files, refresh the repository,
set user permissions, set new label or delete tool as visible in figure
below.</p>
</section>
<section id="svn" class="subject">
<h2>SVN</h2>
<p>
SVN can be enabled enabled as a project tool in the <b>Admin > Tools</b>
page. Once added, a new entry will appear on the project sidebar.
</p>
<p>To use a new repository it is only necessary to checkout the
source code. A command line example is:</p>
<pre class="hint">
svn checkout --username=user http://opensourceprojects.eu/svn/p/project/code/trunk project-code
</pre>
Or to import an existing repository
<pre class="hint">
cd existing-project-code
svn import http://opensourceprojects.eu/svn/p/project/code/ -m "Initial commit"
</pre>
More configuration options for SVN can be accessed at
<p class="hint">
Projects > ProjectName > Tools > Code
</p>
<p>and choose an option within the available from SVN tool's block. It allows to checkout URL, import repository, set visible files, refresh the repository, set user permissions, set new label or delete the tool as depicted.</p>
</section>
<section id="issues" class="subject">
<h2>Issue Tracker</h2>
<div class="col2">
<img class="align-right" src="img/feature-tickets.png">
</div>
<div class="col1">
<p>
Issue management is available on the platform as one of the more important
tools. It directly supports the development process and tickets allow the users
and developers to interact with the project maintainers and main developers. In
this section you get a rough overview of how tickets are configured in a
specific project and how end-users can take advantage of them.
</p>
<p>
Tickets are specific items that correspond to problems identified in the
software, missing features requested by end users, or general communication
items between developers and users. In many tools they are also known as
"issues" or "bugs", and hence the name of issue or bug trackers.
</p>
<p>
The ticket tracker tool is designed to allow for flexibility in how you track
items of work that need to be completed. This includes bugs, feature requests
from end users, or any other task you want to keep track of. You can even
install multiple ticket trackers for different purposes. For example, a large
project could have individual trackers for the design team, the documentation
team, the developers, and another for support. Each of these trackers can have
their own unique list of tickets, as well as custom fields, custom milestones,
and their own "mailing list." Tickets can even be moved between tickets
instances, even if they're on different projects.
</p>
</div>
<h3 class="col1">Installing the Issue Tracker</h3>
<p class="col1">
You can install a new issue tracker instance from the <b>Admin/ Tools</b> and
clicking on the <b>Tickets</b> tool. The new instance that will need a Label (that shows up in the sidebar), and a Mount point (a path in the URL)
</p>
<p class="nocol">
After the tool is installed, you should see a new tool in the
<b>Tools</b> page and in the project sidebar.
Once installed, some configuration options become available in the Tool page.
</p>
<ul>
<li>Field Management
<ul>
<li>Allows administrators to configure how the fields in the ticket tracker appear.</li>
<li>There are several fields you can select from, that are most well suited for your project needs.</li>
</ul>
</li>
<li>Edit Searches
<ul>
<li>If you have a search that you want all users of the tracker to be able to share, you can save that search with a name and it will be placed in the left navigation bar of the tracker for everybody to use.</li>
<li>You can use these saved searches to watch the flow of tickets through the system and make it easier for your development team to focus on groups of active tickets.</li>
</ul></li>
<li>Permissions - Allows you to define the permissions for viewing and resolving tickets.
</li>
<li>Options
<ul>
<li>The default behavior of the Tickets tool can be modified here</li>
<li>Allows for voting tickets up/down, email notifications, and setting up customized help texts</li>
</ul>
</li>
</ul>
<h3>Using the issue tracker</h3>
<p>
With the appropriate permissions, users can create a new ticket using
the Create Ticket link in the left sidebar. At the new ticket form,
fill in a title, and any other appropriate fields, and an issue
description. To edit the main ticket description or fields on an
existing ticket, providing you have the permissions to do so, select
the EDIT button in the upper right of a ticket. If further discussion
about a ticket is needed, use the comment field at the bottom.
</p>
<p>
You can also move and delete tickets. This again depends on your
permissions on the particular instance.�� To move a ticket, select the
Move option in the upper right of the ticket view. To delete a ticket,
select the Trash Can icon in the upper right of the ticket view. This
ticket will now be "deleted", however it may still be "undeleted" if
you select the + icon which replaces the Trash Can icon. If a deleted
ticket matches a list view, there will be a "Show deleted tickets" link
which will allow you to see them.
</p>
<p>
Searching a ticket is also possible. The search uses Solr Lucene query
syntax. On any search page you will see a Help button that will show
the different searches available and some exact examples.
</p>
</section>
<section id="wiki" class="subject">
<h2 class="nocol">Wiki</h2>
<p>The wiki is a collaborative document editor which is easily edited
and can be used for various documentation needs, both internal and
external. By default any project developer can edit the project wiki,
but permissions can be regulated as you wish them to be available to
different user groups. Like most modern wikis, all edits are
non-destructive and a copy of every version is stored.</p>
<p>The wiki can be installed as any other project tool:</p>
<p class="hint"> Admin > Tools</p>
<p>Once installed, new options become available from the Admin/Tools page.
In addition to the common tool options of permissions, Label and
Delete, there are also options specific to the Wiki tool:
</p>
<ul>
<li><b>Set Home</b> defines which page the wiki will redirect to when the base URL is used. By default, this is set to "Home"</li>
<li>The Options page in admin provides you with the ability to add or remove three different pieces of the wiki functionality.
<ul>
<li><b>Show discussion</b> enables user comments on each wiki page</li>
<li><b>Show metadata</b> The author, label, and attachment display near the top of each page</li>
</ul>
</li>
</ul>
<h3>Creating Wiki pages</h3>
<p>Wiki content itself, like the rest of Allura tools, uses <b>Markdown</b>
formatting, along with some additional handling for Artifact Links and
some custom macros.</p>
<p>
New wiki pages can be created from the left sidebar, using the
<b>Create Page</b> button and entering the desired name. Pages can be
referenced within other pages, by putting the new page name in brackets
(e.g. [New page]). Click on a reference that does not exist will also
allow you to create a page.</p>
<p>To edit an existing page, simply use the
pencil icon of Edit link in the upper right of a page.
To add an attachment to a page, first save the page content, as you
may lose unsaved changes otherwise. Select Add attachment button at the
bottom of the edit view.</p>
<h3>Deleting Wiki pages</h3>
<p>To delete a page, enter the edit view as shown above, and then
select the Trash icon in the upper right. Deleting a page will remove
it from view, however the page may still be undeleted if necessary. To
do so, select the + icon when viewing the deleted page. You will then
enter the edit view and you may rename the page as appropriate.</p>
<p>
Deleted pages can be found under the <b>Browse Pages</b> view by selecting the Show
deleted pages link at the bottom of the list.
</p>
</section>
<section id="forum" class="subject">
<h2 class="nocol">Discussion Forums</h2>
<p>Discussion forums are a way to collaborate with other developers on the
project, but they can also be used to discuss with end users. A project
administrator can create as many different forums as needed by clicking
on Add Forum on the left sidebar of the discussion page. To do so you
must have activated the discussion module under tools. It is up to the
administrator to create and name as many forums as required by the
project work flow. You can create as flexible environment as you wish.
</p>
<p>
You may install or remove a Discussion via <b>Admin > Tools</b>.
Once installed, there are a number of configuration options available
for each Discussion instance.
</p>
<p>Most of the fields are standard fields. Those worth to note are as the following:</p>
<ul>
<li><b>Short</b> Name is the short name that forms the URL this forum uses</li>
<li><b>Parent Forum</b> selects a parent if the forum is to be a sub forum of another one</li>
<li><b>Monitoring Email</b> defines the email address where notifications should be sent to</li>
<li><b>Developer Only</b> restricts access to users in the Developers group</li>
</ul>
<p>From the Options page you can edit the Posting Policy of the forum. It determines how moderated posts are handled.</p>
<h3>Using the discussion forums</h3>
<p>
You can create a new thread using the <b>Create Topic</b> link on the left
sidebar of the interface. Enter an
appropriate Subject, Forum, and then enter a Description and post, an
example of this form can be seen in the following figure.
</p>
<img src="img/createtopic.png"/>
<p>To reply to an existing thread you should be viewing the thread.
Select ���reply��� next to a comment to reply to that specific comment, or
use the dialogue box at the bottom of the discussion to add your
comment to the end.</p>
<p>With appropriate permissions, forum moderators have options to edit the
forum. These can be accessed using the pencil icon in the upper right corner.
Moderators can move threads, make announcements, and sticky posts. </p>
</section>
<section id="blog" class="subject">
<h2 class="nocol">Blog</h2>
<p>
The blog may be installed through the tools menu, as described before,
by adding the corresponding tool in the administration area via Admin -
Tools. Once installed, there are a number of configuration options
available for each Blog. In addition to the common tool options of
permissions, Label and Delete, you can determine an external feed.
These external feeds may be updated every three hours and add posts to
the blog accordingly. Multiple feeds may be added, which can serve to
aggregate related news about the project. Unchecking a feed will remove
it from the list.
</p>
<p>
To create a new post, select <b>New Post</b> from the left sidebar under the Blog option. Enter a title and description for the post and Save to publish the post. If you save a draft for later editing before making it public, change the State to Draft before saving. Select the Edit link to edit a post or saved draft. You may also delete a post from the Edit view.
</p>
<p>
Like all Allura tools, the blog uses Markdown syntax. Each blog post will also have a discussion section for users to comment on the post.</p>
</section>
<section id="faq" class="subject">
<h2 class="nocol">FAQ</h2>
<h3><a name="platform-api">Is there an API to access platform?</a></h3>
<p>The platform uses the Allura API, the same API used by Sourceforge.
Tools compatible that are compatible with this API should work with no issues.
If you are writing your own client application, you can check this quick <a href="api/">introduction</a>.
</p>
<h3><a name="projperms">I am having troubles with project permissions ...</a></h3>
<p>The granularity of the access control options can be a bit overwhelming at the start. Have a look at our
documentation <a href="https://opensourceprojects.eu/p/osp/docs/GettingStarted/">wiki</a>, and
check the Projects and Permissions page.
Feel free to start a discussion at the osp project <a href="https://opensourceprojects.eu/p/osp/discussion/">forums</a> or a ticket at the issue <a href="https://opensourceprojects.eu/p/osp/tickets/">tracker<a/></p>
</section>
</div>
</main>
<footer class="site-footer">
<div class="grid-container">
<div class="project-supporters">
<ul class="supporters-logos">
<li>
<img class="suporter-logo logo-ec" src="img/logo-ec.gif" alt="European Comission logo">
</li>
<li>
<img class="suporter-logo logo-prose" src="img/logo-prose.png" alt="PROSE logo">
</li>
</ul>
<p>OpenSourceProjects.eu (OSP) is a software forge funded by the European Comission as part of the PROSE coordination Action and it���s dedicated to hosting Open Source Projects created within EU research projects.</p>
</div>
<nav class="footer-nav">
<ul class="footer-nav-links">
<li class="footer-nav-item"><a href="http://opensourceprojects.eu/about" class="footer-nav-link">About</a></li>
<li class="footer-nav-item"><a href="http://docs.opensourceprojects.eu" class="footer-nav-link">Documentation</a></li>
<li class="footer-nav-item"><a href="http://opensourceprojects.eu/p/osp/discussion/" class="footer-nav-link">Discussion</a></li>
<li class="footer-nav-item"><a href="http://opensourceprojects.eu/p/osp/tickets/" class="footer-nav-link">Report a bug</a></li>
<li class="footer-nav-item"><a href="http://www.ict-prose.eu/" class="footer-nav-link">PROSE CA</a></li>
</ul>
</nav>
<p class="copyright">© 2014 Open Source Projects</p>
</div>
</footer>
</body>
</html>