# Perforce Baseline and Branch Import (P4BBI)

## Welcome 

This is the home of the Perforce Baseline & Branch Import tool, P4BBI.
 
## Introduction 
The P4BBI tool supports the "Baseline & Branch Import" (BBI) migration strategy mentioned in the document [Legacy SCM Migration Strategies](https://swarm.workshop.perforce.com/files/p4bbi/main/docs/LegacySCM-MigrationStrategies.pdf).  This strategy has been used by many companies over the years to quickly migrate from any number of legacy SCM systems to Perforce Helix Core.

## Going Through The Front Door

The BBI approach is "front door" to Perforce.  "Front door" means that it accesses Perforce using the same interface that a human user would, such as the command line interface or published APIs (like P4Perl, P4Python, P4PHP, P4Ruby, P4Java, the C++ API, etc.).  This particular tool uses only the 'p4' command line only.

A key benefit of a front door approach is that it can be operated against a live, running Perforce server, without needing downtime.  Another benefit is that no special permissions are required; only write access to target depot paths is needed (depending on features used; some requrie super user access).  Typically dry runs are performed into a stand-alone test server for verification purposes, and final imports are done into a live server, which may or may not have other projects already in it.
 
## P4D Compatibility

This version of the P4BBI tool tested with P4D 2024.2 servers.  It should work with older and newer versions as well, with some known exceptions:

* Using the RENAME action in BBI config files requires P4D 2009.1+
* Using Streams features requires at least P4D 2011.1, but may may require newer versions depending on stream specs used.

If you just want the latest released version of the file, it is in the Perforce server here:

[https://swarm.workshop.perforce.com/download/p4bbi/main/downloads/p4bbi.tgz](https://swarm.workshop.perforce.com/download/p4bbi/main/downloads/p4bbi.tgz)

## Contact Us

Please contact Perforce Consulting (mailto:consulting-helix-core@perforce.com) for more information.

===

## Contributing by Shelving

All registered Workshop users have **open** access (but not **write**) to the P4BBI project, specifically to these paths:

```
//p4bbi/dev/...
```

The **open** access level confers the ability to edit and **shelve** changes for a pre-commit code review process.  We'll review the change, and either incorporate it or provide feedback. Be sure to provide a detailed change description, and also include the tag/text `#review` in your changelist description before you shelve it, in order to initiate a Swarm code review.  (If you forget, just modify your changelist description to add the `#review` tag, and then force-shelve it again).

Contributing by shelving is ideal if you changes are relatively small in scope, and if they're more solid than experimental.

## Contributing by Branching

Optionally, you may also branch the p4bbi folder, or some subset of it, into your own guest area.  Creating a branch spec is recommended for this purpose, e.g. with a branch spec something like this:

```
Branch:		your_name-p4bbi

Owner:		your_name

Description:
	P4BBI Updates by your_name.

Options:	unlocked
	
View:
	//p4bbi/dev/... //guest/your_name/p4bbi/dev/...
```

Edit, test and submit changes in your branch.  Then when you are done, send us an email [consulting-helix-core@perforce.com](mailto:consulting-helix-core@perforce.com?subject=BBI Pull Request) which servers as a pull request, and tell us what you'd like us to know about your change.

Contributing by branching is a better option of your  changes are larger in scope, or more experimental in nature.

## Guidelines for P4BBI Contributors

* Communicate using [this Swarm page](https://swarm.workshop.perforce.com/projects/perforce_software-p4bbi)!  Follow this project, comment on features, and let folks know what you're planning before you work hard on something that might already be underway.  Or take your own crack at it!
* Review the [list of non-closed jobs](https://swarm.workshop.perforce.com/projects/perforce_software-p4bbi/jobs).  Or you can get that from the command line:

```
p4 jobs -l -e "Project=perforce_software-p4bbi ^Status=closed"
```

* File bugs or feature requests.  Use the 'p4 job' command, setting **Project=perforce_software-p4bbi**, and also set Type field to **Feature** or **Bug**.
* Filing a job is not strictly required, but increases the transparency of what you're doing, and helps promote it.
* Generic changes with a wide appeal are more likely to get implemented.