Contributing to ASL

Overview

We are very excited to allow other developers the opportunity to work on the Adobe Source Libraries with us. Here we will discuss the general guidelines we will use to manage the development and release of the Adobe Source Libraries.

This process is in place to acccomplish the following goals:

• That no malicious, illegal, or third-party code will be submitted to mission-critical code in the depots.
• That more than one ASL developer has a chance to look at the design of code being submitted to ASL.
• That there is always a stable, working copy of the most current code in the code repository.

License Guidelines

All code contributions must be under the Boost Software License - Version 1.0 and copyright of the Adobe opensource project. By contributing code you agree that we can distribute the contribution under the terms of the Boost Software License - Version 1.0, that it can be distributed without any royalties, copyright, trademark, patent or other legal lock ups. Open source means no discrimination against any group or individual that may wish to use the code.

The following boilerplate licensing information must be the first lines of any source file(s) submitted to stlab.adobe.com (where {year} is substituted with the appropriate value, and is the only value that can be altered in the boilerplate):

/*
    Copyright 2007-{year} Adobe Systems Incorporated
    Distributed under the Boost Software License - Version 1.0 (see the accompanying file LICENSE
    or a copy at https://stlab.github.io/adobe_source_libraries/licenses.html)
*/

/**************************************************************************************************/

Submission Guidelines

The fundamental philosophy by which we will manage development and contributions to the ASL is by a sandbox-review method.

The release Depot

The release depot is the official source release of the Adobe Source Libraries. It is updated every release cycle by one of Adobe's stlab.adobe.com developers.

The submission Depot

The submission depot is the current, stable, working release depot. Changes are committed to this depot by an authorized ASL developer pending a review (see below).

The sandbox Depot

The sandbox depot is the main location for hacking. Branches should be made into this depot from submission to allow for developers to code against the current (stable) development state. Developers are encouraged to collaborate with other developers on code and branching of the sandboxes is also acceptable. All branches should reside in the sandbox depot under a top-level user directory.

The Review Process

All developers need to work out of sandboxes created by branching submission into the sandbox depot.

Creating a new branch under the sandbox depot for multiple-developer work is fine, but it should still reside inside a user's folder to avoid too many folders at the top level.

When you are ready to have code reviewed, please post a description of what you have done to adobe-source-devel at lists dot sourceforge dot net list with a review request. An approved review developer will contact you when reviewers are ready and it is ok to go ahead and overwrite the review depot with your working sources.

An approved ASL review developer then engages in a review process with the developer(s) over the contents of the review depot. The review may or may not succeed, or may succeed pending requested changes that must be made back in the sandbox.

When a chunk of code passes review, the approved ASL review developer will integrate the review depot into submission.

Other Enforced Policies

Code formatting is a highly-debated issue between programmers. Adobe is no stranger to many seasoned developers having widely differing formatting styles and preferences. Please try to keep the format of submitted code in line with the rest of the project. We request code submissions to have as close to the same format as what is already present in the code base. Granted, there are inconsistencies in the code base already- we are trying to keep it to a minimum going forward.

All new code submitted to ASL should have a compiling, linking and successfully executable test in the //{depot}/adobe/test/ directory.

All source files (code and documentation) should be named only with lowercase, 7-bit ASCII alphanumeric characters and the underscore ('_') character ([0-9a-z_]). This is to ensure maximum cross-platform, cross-locale compatibility.

For legal reasons, no third-party code is allowed in any stlab.adobe.com depot. Examples of this might be the Boost or Lua library sources. Only code intended for submission to the Adobe Source Libraries is permitted.

Example Client Setup

Client Mapping Specification (clientspec)

The following might be an example of a developer's client specification set up by executing p4 client on the developer's machine. Note that one must first have a development account on the stlab.adobe.com:10666 Perforce depot.

# A Perforce Client Specification.

Client: fbrereto

Owner:  fbrereto

Description:
    This is the client specification for Foster Brereton's primary development machine.

Root:   /Users/fbrereto/opensource/

Options:    noallwrite noclobber compress unlocked nomodtime normdir

LineEnd:    local

View:
    //release/... //fbrereto/release/...
    //review/... //fbrereto/review/...
    //sandbox/fbrereto/... //fbrereto/sandbox/fbrereto/...
    //submission/... //fbrereto/submission/...

Note in the above that the 'compress' flag is set. This will generally speed up transactions between your computer and the stlab.adobe.com Perforce depot.

Sandbox Branch Specification (branchspec)

A branchspec is used to map the submission depot to your personal working sandbox. You create a branchspec with the p4 branch {name}_sandbox command, where {name} is your account name on the stlab.adobe.com Perforce server.

Updates made to the submission depot can then be integrated with the p4 integrate -1 -d -i -t -b {name}_sandbox command (followed by a p4 resolve to merge potential conflicts).

Integrating your sandbox to the review depot is as simple as executing p4 integrate //sandbox/{name}/sandbox... //review/.... Note that you should purge the contents of the review with a p4 delete //review/... first (once you are OK'd to do so by the ASL review developer).

Below is a sample branchspec to map submission to a user's sandbox. Note that the map goes to a sandbox directory within the user's directory to allow for other directories in the sandbox (including other sandboxes):

# A Perforce Branch Specification.

Branch: fbrereto_sandbox

Owner:  fbrereto

Description:
    Maps submission to Foster Brereton's working sandbox.

Options:    locked

View:
    //submission/... //sandbox/fbrereto/sandbox/...

Note in the above that the 'locked' flag is set.

Conclusion

Hopefully this results in an environment in which people are comfortable working, ultimately resulting in the best code we can produce as a community. Please let us know if you have any questions or comments- we would love to hear them. Thank you again for the interest you have expressed in the Adobe Source Libraries and the contributions you have made thus far!