Quick Start Guide
Setting up your Account
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.
To login with your existing account, click the top left corner login-link and insert your username and password.
You can change your profile’s settings from the Settings 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.
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.
Choosing Profile 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.
You can create new projects from the projects list (from the top menu under Projects) This opens a list of projects available to you. To create one of your own, click the Add a Project button from the left side menu. This opens the project creation page.
From this page you can select the name of the project, and some of the initial project settings:
- Project Name(3-15 characters long
- Project URL name, http://opensourceproject.eu/p/url-name
- The tools that will be enabled for this project
- Whether the project is private or not
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.
Installing new Tools
You can install new tools in your project from the Admin/ Tools 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)
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.
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 Admin/ Tools selection.
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
Admin > Tools
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.
After the pop-up window is dismissed, the new Subproject tool will be listed along with the other installed tools.
Permissions and access control
The key part of enforcing access control for a project takes place in the User Permissions page, at
Admin > User Permissions
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.
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.
GIT can be enabled enabled as a project tool in the Admin > Tools 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).
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:
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://email@example.com/git/p/newproject/code-0 git push origin master git branch --set-upstream master origin/master # so 'git pull' will work later
Or If using Git with an existing repository:
cd myproject git remote add origin http://firstname.lastname@example.org/git/p/newproject/code-0 git push origin master git branch --set-upstream master origin/master # so 'git pull' will work later
To manage the Git tool, go to Tools page under
Projects > ProjectName > Tools > Code
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.
SVN can be enabled enabled as a project tool in the Admin > Tools page. Once added, a new entry will appear on the project sidebar.
To use a new repository it is only necessary to checkout the source code. A command line example is:
svn checkout --username=user http://opensourceprojects.eu/svn/p/project/code/trunk project-codeOr to import an existing repository
cd existing-project-code svn import http://opensourceprojects.eu/svn/p/project/code/ -m "Initial commit"More configuration options for SVN can be accessed at
Projects > ProjectName > Tools > Code
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.
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.
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.
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.
Installing the Issue Tracker
You can install a new issue tracker instance from the Admin/ Tools and clicking on the Tickets tool. The new instance that will need a Label (that shows up in the sidebar), and a Mount point (a path in the URL)
After the tool is installed, you should see a new tool in the Tools page and in the project sidebar. Once installed, some configuration options become available in the Tool page.
- Field Management
- Allows administrators to configure how the fields in the ticket tracker appear.
- There are several fields you can select from, that are most well suited for your project needs.
- Edit Searches
- 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.
- 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.
- Permissions - Allows you to define the permissions for viewing and resolving tickets.
- The default behavior of the Tickets tool can be modified here
- Allows for voting tickets up/down, email notifications, and setting up customized help texts
Using the issue tracker
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.
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.
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.
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.
The wiki can be installed as any other project tool:
Admin > Tools
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:
- Set Home defines which page the wiki will redirect to when the base URL is used. By default, this is set to "Home"
- The Options page in admin provides you with the ability to add or remove three different pieces of the wiki functionality.
- Show discussion enables user comments on each wiki page
- Show metadata The author, label, and attachment display near the top of each page
Creating Wiki pages
Wiki content itself, like the rest of Allura tools, uses Markdown formatting, along with some additional handling for Artifact Links and some custom macros.
New wiki pages can be created from the left sidebar, using the Create Page 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.
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.
Deleting Wiki pages
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.
Deleted pages can be found under the Browse Pages view by selecting the Show deleted pages link at the bottom of the list.
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.
You may install or remove a Discussion via Admin > Tools. Once installed, there are a number of configuration options available for each Discussion instance.
Most of the fields are standard fields. Those worth to note are as the following:
- Short Name is the short name that forms the URL this forum uses
- Parent Forum selects a parent if the forum is to be a sub forum of another one
- Monitoring Email defines the email address where notifications should be sent to
- Developer Only restricts access to users in the Developers group
From the Options page you can edit the Posting Policy of the forum. It determines how moderated posts are handled.
Using the discussion forums
You can create a new thread using the Create Topic 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.
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.
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.
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.
To create a new post, select New Post 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.
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.
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 introduction.
The granularity of the access control options can be a bit overwhelming at the start. Have a look at our documentation wiki, and check the Projects and Permissions page. Feel free to start a discussion at the osp project forums or a ticket at the issue tracker