[Documentation] Add package edit documentation #794

ankitspd · 2016-11-16T17:55:20Z

https://bugs.swift.org/browse/SR-3115

abertelrud · 2016-11-16T22:39:28Z

Documentation/Usage.md

+
+    $ swift package edit Foo --revision 969c6a9
+
+This is similar to previous version except that SwiftPM will leave the dependency at a detched HEAD on the specified revision.


Is it possible to just do swift package edit Foo to leave it at the currently checked out revision, or does a revision or branch always need to be specified? (it feels like we discussed this when discussing the swift-evolution proposal but I don't remember now where we came down on this)

If one or the other always has to be specified, then perhaps that should be explicitly stated and the rationale given, since it feels very natural to want to just do swift package edit Foo.

Agree we should clarify this.

abertelrud · 2016-11-16T22:40:17Z

Documentation/Usage.md

+    $ swift package unedit Foo # --force
+
+This will remove the edited dependency from Packages/ and put the originally resolved version back. This command will fail if there are uncommited changes or changes which are not
+pushed to the remote repository. The `--force` option can be used to forcefully unedit a dependency.


Should probably clarify that this will discard the edits (assuming that's what it does).

I agree, I would probably explain what unedit does, then explain what --force does.

ddunbar

This is great, thanks!

ddunbar · 2016-11-17T16:52:46Z

Documentation/Usage.md

+
+### Editable Packages
+
+SwiftPM supports editing dependencies, which means moving it into a location under `Packages/` directory. 


I've tried not to use the "SwiftPM" abbreviation in the docs.

I think this should say more about the why rather than that it moves it into Packages. For example, "support editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API)."

ddunbar · 2016-11-17T16:54:08Z

Documentation/Usage.md

+
+SwiftPM supports editing dependencies, which means moving it into a location under `Packages/` directory. 
+
+If a such an editable package is present in Packages, then swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.


Rather than say "present in Packages", I would talk about "packages which are in the editable state".

ddunbar · 2016-11-17T16:54:37Z

Documentation/Usage.md

+
+    $ swift package edit Foo --revision 969c6a9
+
+This is similar to previous version except that SwiftPM will leave the dependency at a detched HEAD on the specified revision.


Agree we should clarify this.

ddunbar · 2016-11-17T16:55:15Z

Documentation/Usage.md

+    $ swift package unedit Foo # --force
+
+This will remove the edited dependency from Packages/ and put the originally resolved version back. This command will fail if there are uncommited changes or changes which are not
+pushed to the remote repository. The `--force` option can be used to forcefully unedit a dependency.


I agree, I would probably explain what unedit does, then explain what --force does.

ddunbar · 2016-11-17T16:55:27Z

Documentation/Usage.md

+This will remove the edited dependency from Packages/ and put the originally resolved version back. This command will fail if there are uncommited changes or changes which are not
+pushed to the remote repository. The `--force` option can be used to forcefully unedit a dependency.
+
+You can read the complete Swift evolution proposal [here](https://github.com/apple/swift-evolution/blob/master/proposals/0082-swiftpm-package-edit.md).


I'm not sure we should have this. Users should never really need to read this to understand the feature.

I figured it would be good if there is a reference to it, it is not meant to serve as documentation, What if I drop "complete" from the sentence ?

ddunbar · 2016-11-17T17:15:36Z

Documentation/Usage.md

+
+### Editable Packages
+
+Swift Package Manager supports editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API). The Package Manager moves the dependency into a location under `Packages/` directory where can be edited.


... it can ...

Package Manager -> package manager

ddunbar · 2016-11-17T17:15:45Z

Documentation/Usage.md

+
+Swift Package Manager supports editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API). The Package Manager moves the dependency into a location under `Packages/` directory where can be edited.
+
+For the packages which are in the editable state, swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.


swift build (formatting)

"it's" -> "its"

"just build" -> just build (formatting)

ddunbar · 2016-11-17T17:16:51Z

Documentation/Usage.md

+
+For the packages which are in the editable state, swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.
+
+When an editable package is present, it will be used to satisfy all instances of that Package in the depencency graph. It is possible to edit all, some, or none of the packages in a dependency graph, without restriction.


Package -> package

ddunbar · 2016-11-17T17:17:19Z

Documentation/Usage.md

+
+When an editable package is present, it will be used to satisfy all instances of that Package in the depencency graph. It is possible to edit all, some, or none of the packages in a dependency graph, without restriction.
+
+Editable package are best used to do experimentation with dependency code or create and submit a patch in the dependency owner's repository (upstream).


packages (plural)

I would merge this short sentences into at least one less paragraph

ddunbar · 2016-11-17T17:18:12Z

Documentation/Usage.md

+
+This is similar to previous version except that the Package Manager will leave the dependency at a detched HEAD on the specified revision.
+
+Note: It is necessary to provide either branch or revision option. The rationale here is that checking out the currently resolved version would leave the repository on a detached HEAD, which is confusing. Explict options makes the action predictable for user.


either a branch

ddunbar · 2016-11-17T17:18:40Z

Documentation/Usage.md

+
+Note: It is necessary to provide either branch or revision option. The rationale here is that checking out the currently resolved version would leave the repository on a detached HEAD, which is confusing. Explict options makes the action predictable for user.
+
+Once a package is in editable state, you can navigate to the directory `Packages/Foo` make changes, build and then push the changes to the upstream repository.


in an editable

... to make

maybe add "or submit a pull request" or so

- https://bugs.swift.org/browse/SR-3115

ankitspd assigned ddunbar and abertelrud Nov 16, 2016

ankitspd force-pushed the pkg-edit-doc branch from 29bd682 to a5f8faf Compare November 16, 2016 17:55

abertelrud approved these changes Nov 16, 2016

View reviewed changes

ankitspd force-pushed the pkg-edit-doc branch from a5f8faf to c94c4c5 Compare November 17, 2016 16:55

ddunbar approved these changes Nov 17, 2016

View reviewed changes

ddunbar assigned ankitspd and unassigned ddunbar Nov 17, 2016

ankitspd force-pushed the pkg-edit-doc branch from c94c4c5 to 353539f Compare November 17, 2016 17:14

ankitspd assigned ddunbar and unassigned ankitspd Nov 17, 2016

ddunbar approved these changes Nov 17, 2016

View reviewed changes

ddunbar removed their assignment Nov 17, 2016

ankitspd force-pushed the pkg-edit-doc branch from 353539f to 3cc466f Compare November 17, 2016 17:32

[Documentation] Add package edit documentation

315eec6

- https://bugs.swift.org/browse/SR-3115

ankitspd force-pushed the pkg-edit-doc branch from 3cc466f to 315eec6 Compare November 17, 2016 17:33

ankitspd merged commit a1f4dd1 into apple:master Nov 17, 2016

ankitspd deleted the pkg-edit-doc branch November 17, 2016 17:35

ankitspd mentioned this pull request Nov 21, 2016

[SR-3115] Document swift package edit #5183

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Documentation] Add package edit documentation #794

[Documentation] Add package edit documentation #794

ankitspd commented Nov 16, 2016

abertelrud Nov 16, 2016

ddunbar Nov 17, 2016

abertelrud Nov 16, 2016

ddunbar Nov 17, 2016

ddunbar left a comment

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ankitspd Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016

ddunbar Nov 17, 2016


		$ swift package edit Foo --revision 969c6a9

		This is similar to previous version except that SwiftPM will leave the dependency at a detched HEAD on the specified revision.


		### Editable Packages

		SwiftPM supports editing dependencies, which means moving it into a location under `Packages/` directory.


		SwiftPM supports editing dependencies, which means moving it into a location under `Packages/` directory.

		If a such an editable package is present in Packages, then swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.


		### Editable Packages

		Swift Package Manager supports editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API). The Package Manager moves the dependency into a location under `Packages/` directory where can be edited.


		Swift Package Manager supports editing dependencies, when your work requires making a change to one of your dependencies (for example, to fix a bug, or add a new API). The Package Manager moves the dependency into a location under `Packages/` directory where can be edited.

		For the packages which are in the editable state, swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.


		For the packages which are in the editable state, swift build will always use the exact sources in this directory to build, regardless of it's state, git repository status, tags, or the tag desired by dependency resolution. In other words, this will "just build" against the sources that are present.

		When an editable package is present, it will be used to satisfy all instances of that Package in the depencency graph. It is possible to edit all, some, or none of the packages in a dependency graph, without restriction.


		When an editable package is present, it will be used to satisfy all instances of that Package in the depencency graph. It is possible to edit all, some, or none of the packages in a dependency graph, without restriction.

		Editable package are best used to do experimentation with dependency code or create and submit a patch in the dependency owner's repository (upstream).


		This is similar to previous version except that the Package Manager will leave the dependency at a detched HEAD on the specified revision.

		Note: It is necessary to provide either branch or revision option. The rationale here is that checking out the currently resolved version would leave the repository on a detached HEAD, which is confusing. Explict options makes the action predictable for user.


		Note: It is necessary to provide either branch or revision option. The rationale here is that checking out the currently resolved version would leave the repository on a detached HEAD, which is confusing. Explict options makes the action predictable for user.

		Once a package is in editable state, you can navigate to the directory `Packages/Foo` make changes, build and then push the changes to the upstream repository.

[Documentation] Add package edit documentation #794

[Documentation] Add package edit documentation #794

Conversation

ankitspd commented Nov 16, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ddunbar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment