Skip to main content
Version: 0.1.139

Creating a project

A project pairs one legacy codebase with the modern codebase being built from it. Everything else — the specification, the implementations, the test runs — hangs off that pair.

Before you start​

You need edit access to create a project, and your installation needs a valid licence. An unlicensed installation will tell you so on every screen and explain how to get one.

Start from New project on the dashboard (or, before you have any projects, from the dashboard's empty state). The page asks for the legacy codebase first, then where the modernized codebase comes from, and Create project takes you straight to the new project.

The legacy codebase​

Drop the legacy source as one or more ZIP archives. The project name is filled in from the first archive's file name until you type one of your own. A file that is not a ZIP, or one you have already added, is skipped and the page says so. A few things happen to the archives on the way in, and it is worth knowing about them because they change what you see afterwards.

If the project is created but its archives fail to upload, the page says so and keeps what you entered: pressing Create project again retries the upload into the same project rather than creating a second one.

  • Oversized uploads are refused, not truncated. If the archive exceeds the limit your operator configured, the upload fails and nothing is stored. A partially ingested codebase would produce a specification with holes in it and no sign that anything was missing.
  • An archive that expands without bound is refused mid-extraction, and a refused upload leaves nothing behind.
  • A single wrapping folder is flattened. If your archive contains one top-level directory with the project inside it, that directory is unwrapped rather than treated as the codebase root.
  • Non-UTF-8 source is converted before anything reads it. Legacy code in a regional encoding would otherwise reach the analysis as mojibake. The originals are kept, and a project ingested before conversion existed is found and offered one.

The modernized codebase​

The choice is made when the project is created, from four options.

Start a new app. The platform generates a new application on the target stack you choose, and owns its structure from the start.

Upload a ZIP. An existing modernized application, imported as-is.

Clone one repository or Combine several repositories. You point the project at code you already have — on GitHub, Azure DevOps, Team Foundation Server or GitLab — and the platform clones it. You do not declare its toolchain: the platform detects what it is built with from its build files and tells the agents, and every project runs on one environment that carries Node, Java and .NET, so Repave IDE and previews open whatever the stack. What a provided codebase needs that a scaffolded one does not is:

  • Its unit test configuration — where the suites are, how to run them, how coverage is reported. The platform detects this by running the suites, and reports why it will not run if detection fails rather than guessing.

Connecting to a repository​

GitHub and Azure DevOps connect with a personal access token. Team Foundation Server connects without deployment configuration, and where your server presents a private certificate authority you can trust it from the UI, or skip TLS verification for that one connection if you must.

GitLab connects with a personal access token that has the api scope, which Repave needs to open merge requests. The address starts as https://gitlab.com; change it only for a self-managed GitLab, to the address you open GitLab at. For a self-managed GitLab, Certificate options lets you supply a private certificate authority or skip TLS verification, as for Team Foundation Server, and opens on its own if your server's certificate isn't trusted. Projects in subgroups are listed by their full path. In pull-request mode, a GitLab project's pull requests are merge requests on GitLab.

Projects that combine several repositories​

A system split across several repositories can be one project. Choose Combine several repositories, pick the git connection, and tick the repositories. Every repository comes from that one connection. Each gets a folder in the combined workspace, named after the repository, and its default branch; you can change either. A repository with no branches yet can't be combined.

The combined workspace is built in a workspace repository. By default Repave creates it for you, empty and private, named after the project, in the same owner, group or team project as the first repository you ticked; you can change the name and where it goes. If you would rather use one you have made, choose Use an existing empty repository: it must have no commits, and Repave says so before creating the project if it has any. One workspace repository serves one project. The folder where the shared BDD features and end-to-end scripts live is under Advanced; most projects keep its default.

After creation, the source repositories are managed from project settings, changes are pulled in from each, and work done in the combined workspace is pushed back out to the repositories it belongs to.

The combined workspace is rebuilt from the repositories each time they change, so a change made directly in it, under one repository's folder, would be overwritten. When Repave finds one it stops the sync and the banner on the project page reads "Changes were made under … on the combined branch that haven't been sent to those repositories." Send to source repositories opens a pull request for the change in each repository it touches, takes it off the combined branch, and syncs again; review and merge the pull requests, then sync to bring the change back. Nothing is merged or discarded: the change stays in the combined branch's history and in the pull requests. You need edit access to the project to send changes.

What runs on upload​

Ingestion is not the end of it. The platform indexes the codebase, counts what is there, and begins the analysis that produces the as-is specification. You can watch this on the Analysis Jobs page — see Jobs — and you do not have to wait on that page for it to proceed.

The code index is a separate thing worth knowing about: two project settings decide whether it runs, it says what state it is in, and it can be rebuilt. Each codebase in a project is indexed separately and each is kept current as commits land.

When it is ready​

The project summary shows lines of code for the legacy and modernized codebases, and feature coverage closure — how much of what was discovered has been decided and built. When features start appearing under Discovered Features, the analysis has produced something to review.

Next: Reading the analysis.