Jump to: navigation, search

Skalli/FAQ

< Skalli
Revision as of 06:05, 8 January 2013 by Michael.ochmann.sap.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Skalli
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse SourceProject Set File

General Questions

Is there some documentation?

There is a ​Quick Walkthrough available showing the most important screens and concepts. Besides that, just start exploring Skalli yourself! Download and run the all-in-one installation. It includes a bunch of example projects to play with. Search for projects you are interested in or just wander through the ​project hierarchy. Consume the information projects provide on their detail pages. A good starting point may be ​Skalli's own landing page.

What is Skalli about?

Skalli is about searching for and publishing of useful information about projects. And with project we do not necessarily mean software projects, although with the currently existing plugins and extensions it is best suited for software projects. Each project has a detail page collecting all information the project owners maintained for that project, or Skalli was able to derive from other sources. Typcially you'll find links to the project's source code, wiki pages and other documentation, contact information like mailing lists and a list of people involved with the project. Furthermore, Skalli provides some self-service, e.g. a Gerrit connector to create Git repositories for a project.

Is Skalli extensible?

Yes, and that was one of the most important design goals from the beginning. You can extends the project model, the UI and the backend. The technology used for extensions is based on OSGi services. Check out the tutorials on how to implement extensions for Skalli.

What technology is Skalli based on?

Skalli is a native OSGi application running on any OSGI-enabled web container, such as Virgo or Jetty RT. The user interface is a mixture of plain JSP and embedded ​Vaadin components.

Project Lifecycle

How can I create a project?

Just follow the Create Project link on the welcome page. Choose a suitable project template (likely you want to use the default). Enter a Project ID and a Display Name for your project. The project id is a symbolic name like technology.skalli, which follows the rules for Maven identifiers and is simple enough to be used whenever a technical identifier is required, for example in URLs. The display name represents your project in the UI and is the most important input for the search besides the description.

You may be suprised now, but that's basically is it! Press "OK" and admire you project's detail page. You are going to fill in tons of additional useful information hopefully soon, but you should now start developing.

One final note: If you want to know, why Skalli claims that your freshly created project has errors, continue reading in the section "Improving Data Quality".

What is the difference between a project and a component?

Projects in the philosophy of Skalli are Projects of People, i.e. they represent a group of people working on a topic. This topic usually, but not necessarily, is some piece of software, but may as well be a book or a building. Projects are the entities to which you assign committers and product owners, homepages, tags and mailing lists --- with one word: useful informnation that helps people participating in your project, either by consuming it or by contributing to it.

Components on the other side are there to represent the more technical aspects of a project. You typically assign source code repositories, build jobs and bugtracking systems to components rather than to projects, but Project Portal does not enforce that. It is perfectly fine to assign development information to a project and a homepage to a component if that is what your project suits best. Projects/components can even inherit information from their parent project/component (see below).

There is only one restriction: In the project hierarchy projects can have projects and components as subunits, but components can have only other components as subunits, never projects.

Can I rename a project?

Yes you can. Each project has a total of three names, and two of them can be changed later on:

  • a symbolic name like technology.skalli, which is for example used in the URL of the project's detail page, e.g. http://skalli.example.org/projects/technology.skalli. Symbolic names have to be unique among all projects. You can change the symbolic name any time, but note that links other people might have for your project, will likely break. The name of a Git repository depot as well as other names associated with your project like bundle and Maven group/artifact identifiers will not be affected by changing the symbolic name.
  • a display name like Skalli. You will see that display name everywhere in the UI, e.g. as title of the project's detail page and in search hits. You can change the display name, too.
  • an internal UUID that is assigned once the project is created, and never changed afterwards. You can retrieve a project's UUID via the REST API. Knowing the UUID of a project you may create real "permanent links" by replacing the symbolic name with the UUID, e.g. http://skalli.example.org/projects/5856b08a-0f87-4d91-b007-ac367ced247a.

How can I delete a project?

By setting the deleted flag in the Basic section of the edit dialog. Note, this may require administrator rights depending on the permissions configuration. Deleting a project does not physically remove it from Skalli's database, but just makes it invisible for search operations, removed it from the project hierarchy view and hides the project's detail page. Note that you still can get to the detail page if you know the project's permanent URL, e.g. http://skalli.example.org/projects/5856b08a-0f87-4d91-b007-ac367ced247a.

Instead of deleting the project you might also consider setting the Project Phase in the edit form to Abandoned, Closed or Completed. This way, people could stil find the project and consume for example source code or documentation ... or maybe even continue the project?

Note that deleting a project in Skalli does not mean that a Git repository associated with the project (or any other resources associated with it) will be deleted automatically as well.

Can deleted projects be revived?

Yes. Navigate to http://skalli.example.org/deletedprojects and search the project in question. Or use the projects's permanent URL, e.g. http://skalli.example.org/projects/5856b08a-0f87-4d91-b007-ac367ced247a, to navigate to the project's detail page. Use the edit link and remove the deleted flag in the Basic section of the edit dialog. The project is revived in the last state before the deletion, but note that in rare cases it might be necessary to choose another symbolic name, if another project has grabbed it in the meantime.

Note, reviving projects may require administrator rights depending on the permissions configuration.


Improving Data Quality

Skalli claims that my project has errors! What does that mean?

First of all: Don't panic! Those error markers, and sometimes you will see warning or info markers as well, at the top of your project's detail page are just hints and reminders to help you improving your project's metadata quality. For example, you might not have entered a description for your project yet, resulting in an ERROR marker. Errors are serious problems that you should fix as soon as possible --- in this case because the description is one of the most important search parameters and it is in your own best interest to help other people finding your stuff, isn't it? --- but world will not end and you will not be punished for not providing that damn description. If you are fine with that, Skalli is fine too.

Besides that, there are warnings to indicate issues that are not serious, but should be fixed anyway. A typical case is a description that just repeats the project name. Finally, info markers are hints how the data quality of your project could be improved further.

Why does Skalli not prevent me from saving a project with issues?

It does, but it prevents you only from saving projects when there are FATAL issues. For example, entering some arbitrary text into a field where a URL is expected, leads to a FATAL issue that you must correct before you can save the project. In general, only mistakes that prohibit Skalli from persisting the project's metadata, lead to FATAL issues.

On the other side, a missing description or an invalid homepage URL might be serious problems, but they are not sufficient reasons for hindering you starting to develop your project! Fix these problems if and when you think it is appropriate, or just ignore them.

If you want to check your project for issues before saving it, click on the Check button in the top or bottom button bar.

Who can see the issues of my project?

Only project members and members of projects up in the project hierarchy can see issue markers for their projects. These markers are there to help you, not to blame someone.

Skalli falsely claims a problem with a URL! Is that a bug?

Yes and no. More likely, no. Some hosts require credentials that Skalli may not be able to provide. Or a website may not have permanent links, or not allow deep links. Nevertheless, we think that a tool that checks for broken URLs in your project's metadata is valuable as such, even if it produces some false positives.

For the time being, just ignore these errors. Or vote for [1].