<div dir="ltr"><div>Thank you all for the valuable feedback I have updated the proposal to reflect the changes which are agreed upon by majority. Please go through the updated proposal below and provide more feedback. </div><div><br></div><div><div><br></div><h1 id="toc_0" style="margin-right:0px;margin-bottom:10px;margin-left:0px;padding:0px;font-size:28px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;margin-top:0px!important">Lock File for Swift Package Manager</h1><h2 id="toc_1" style="margin:0px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Introduction</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">A Package.lock file containing list of resolved dependencies generated by swiftpm.</p><h2 id="toc_2" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Motivation</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> file can be helpful in situations like :</p><h3 id="toc_3" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Reproduce exact versions of dependencies on different machine</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Multiple developers working on a package would want to use the exact versions(including minor and patch) of the dependencies declared in the manifest file</li><li style="margin:0px">When a build is being performed on a remote machine eg CI </li></ul><h3 id="toc_4" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Pointing a dependency to an untagged commit</h3><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">Sometimes it might be helpful to lock a dependency to a particular commit ref for which a tagged version is unavailable in cases such as :</p><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Forking a 3rd party library and making it swiftpm compatible for temporary use until officially supported by the author</li><li style="margin:0px">Package is in active development and not ready for a release tag</li></ul><h2 id="toc_5" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Proposed Solution</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">swiftpm generates a simple <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> file after resolving the dependency graph for that package in some simple format.</p><h2 id="toc_6" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Detailed Design</h2><h2 id="toc_7" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Package.lock aka the lock file</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> is a plain text auto-generated file containing list of resolved dependencies: one line per dependency in format</p><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"> <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">&lt;gitURL&gt; &lt;resolvedVersion&gt;</code></p><pre style="margin-top:15px;margin-bottom:15px;background-color:rgb(248,248,248);border:1px solid rgb(204,204,204);font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;color:rgb(0,0,0)"><code class="" style="margin:0px;padding:0px;border:none;background-color:transparent;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">&quot;<a href="http://github.com/foo/bar">github.com/foo/bar</a>&quot; &quot;v1.1&quot;
&quot;../mygitdir&quot; &quot;v2.3&quot;
&quot;<a href="http://github.com/my/forked/dep">github.com/my/forked/dep</a>&quot; &quot;8b3989be184375ae6e84e8a0254e5258789b23e5&quot;</code></pre><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> will always contain the exact version of the dependency resolved by SPM</li><li style="margin:0px">User is expected to commit the lock file into the git repo for others to reproduce the exact versions of dependencies on their system</li><li style="margin:0px">lock file of dependencies are ignored and only their Package.swift is taken into consideration for resolving all the dependencies</li></ul><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">User is not expected to interact with this file as it&#39;ll always be generated by SPM so it might make sense to:</p><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">not to use swift syntax in this file.</li><li style="margin:0px">keep it seperate from Package.swift to avoid confusion for new users.</li></ul><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">Another option could be using very minimal valid swift syntax for eg :</p><pre style="margin-top:15px;margin-bottom:15px;background-color:rgb(248,248,248);border:1px solid rgb(204,204,204);font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;color:rgb(0,0,0)"><code class="" style="margin:0px;padding:0px;border:none;background-color:transparent;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">[
 (&quot;<a href="http://github.com/foo/bar">github.com/foo/bar</a>&quot;, &quot;v1.1&quot;), 
 (&quot;../mygitdir&quot;,&quot;v2.3&quot;),
 (&quot;<a href="http://github.com/my/forked/dep">github.com/my/forked/dep</a>&quot;,&quot;8b3989be184375ae6e84e8a0254e5258789b23e5&quot;)
]</code></pre><h2 id="toc_8" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Workflow</h2><h3 id="toc_9" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;font-size:inherit">$ swift build</code> :</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px"><p style="margin:0px 0px 15px">Dependencies declared in <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.swift</code> and <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> is not present :</p><p style="margin:15px 0px">Resolves <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.swift</code> and generates <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code>; uses the generated <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> to fetch and build the dependencies</p></li><li style="margin:0px"><p style="margin:0px 0px 15px"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> already present :</p><p style="margin:15px 0px">Uses the generated <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.lock</code> to fetch and build the dependencies.</p><p style="margin:15px 0px">if <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.swift</code> has been modified SPM generates a warning for user to consider updating the lock file using <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --update</code> (explained below)</p></li><li style="margin:0px"><p style="margin:0px 0px 15px">Packages/ is out of sync with lock file :</p><p style="margin:15px 0px"><strong style="margin-top:0px">Uncommited changes in Packages/</strong> : User is probably trying to modify the dep so suggest him to use the <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --ignore-lock</code> command (explained below)</p><p style="margin:15px 0px"><strong style="margin-top:0px">Commited changes in Packages/</strong> : User is done making changes in the dependency but forgot to lock them so HEADs don&#39;t match, suggest him to use <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --lock</code> command (explained below)</p></li></ul><h3 id="toc_10" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;font-size:inherit">$ swift build --update</code> :</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Remove current Package.lock if present and re-resolve Package.swift to generate a new Package.lock file for all the deps.</li><li style="margin:0px">To update only one dependency use <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --update=&lt;dep_name&gt;</code></li></ul><h3 id="toc_11" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;font-size:inherit">$ swift build --lock</code> :</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Locks the current HEAD packages in Packages/ and writes them into the lock file uses tags where available otherwise refs</li><li style="margin:0px">To lock only one dependency use <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --lock=&lt;dep_name&gt;</code></li></ul><h3 id="toc_12" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif"><code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;font-size:inherit">$ swift build --ignore-lock</code> :</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Ignores the lock file and use HEAD of Package/ to build the deps without writing to lock file</li><li style="margin:0px">Useful for development</li></ul><h3 id="toc_13" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Workflow for Pointing a dependency to an untagged commit</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Create <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">Package.swift</code> and declare dependencies</li><li style="margin:0px">Run <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build</code> to resolve and build the Package</li><li style="margin:0px">Modify and play with the checkedout dependencies in Packages/</li><li style="margin:0px">Commit and push the changes to the git remote mentioned in Package.swift</li><li style="margin:0px">Once satisfied with the current state of a package lock it using <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --lock=&lt;dep_name&gt;</code></li><li style="margin:0px">Commit the lock file and push for others to use</li></ul><h3 id="toc_14" style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">If a dependency(foo) is using a dependency(bar) with an untagged commit</h3><ul style="margin:15px 0px;padding-left:30px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px"><li style="margin:0px">Author of foo mentions in their readme that they&#39;re using bar on an untagged commit</li><li style="margin:0px">Package(baz) wanting to use foo and bar both will need to lock his bar package to same untagged commit</li></ul><h2 id="toc_15" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Impact on existing code</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px">None on the code but old users will not be able to run <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build</code> with changes in their Packages/ which is possible right now, they&#39;ll need to use <code style="margin:0px 2px;padding:0px 5px;white-space:nowrap;border:1px solid rgb(234,234,234);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">$ swift build --ignore-lock</code> instead which will be communicated using warnings as stated above.</p><h2 id="toc_16" style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif">Alternatives Considered</h2><p style="margin-top:15px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,sans-serif;font-size:14px;margin-bottom:0px!important">One alternative is to allow mentioning refs in manifest file while declaring a dependency but as discussed in <a href="file:///Users/aciid/Dropbox/notes/%22https://lists.swift.org/pipermail/swift-build-dev/Week-of-Mon-20151214/" style="color:rgb(65,131,196)">this</a> thread it might not be the best idea.</p></div><div><br></div><div><br></div><br><div class="gmail_extra"><div class="gmail_signature"><br></div>
</div></div>