3

Closed

Feature Request: Automatically open important files (e.g. readme.txt, setup.cs)

description

Basically the idea is to be able to mark files in your package as “readme” files. This indicates that the package developer feels that the package consumer should read/modify the files before using the package.

What will happen with such marked files is dependent on the client/context in which the package is installed:
  • When installed inside VS the readme files would automatically be opened. This is modeled after the VS project template feature that allows some files to be automatically opened in the editor after the project is created.
  • When installed outside VS the runner could either open them with notepad.exe (or maybe the defautl system text editor, so that this also works in a Mono environment) or to keep things simpler, simply print a message “Package A indicates that you should look at file Readme.txt first”.
This feature could be useful for:
  • Simple Readme.text files
  • Configuration files (such as .config or maybe even configuration source files - for example useful for an MVC pacakage that adds some custom routes via a source file)
  • Other instructions about manual steps necessary to activate the package
Closed May 8, 2012 at 6:00 PM by CodePlexAdmin
Bulk resetting Issues that were moved to Fixed from Closed due to CodePlex bug.

comments

davidebb wrote Oct 8, 2010 at 8:59 PM

Yes, we did discuss that a while back. I’d like to do this as pure convention driven. e.g. if you have a file named readme.txt or readme.htm at the root, we will treat it as such. I don’t think we ever need more than one, as it would make it tricky for the client to show them all.

Corner case: when installing a package with dependencies, you could end up with multiple readme's getting opened. And that's not really a big deal IMO.

marcind wrote Oct 8, 2010 at 9:42 PM

I disagree with the convention-based approach. I see this feature as also being about bringing an important file to the developers attention. For example I might have a MyPackageInit.cs file that I install into the project root that the developer needs to modify manually to configure my package. It's not just about a 'readme' file but also about 'start here' files.

Haacked wrote Oct 8, 2010 at 9:56 PM

The "convention based" issue is orthogonal to the opening the readme. I think Ebbo is stating that we'll always open a file named according to the convention. So you don't have to explicitly mark the readme.

bsimser wrote Oct 9, 2010 at 1:30 AM

This is very similar to what github does. Create a file called README (with any extension, or no extension) and it will display it. It's a good idea. An enhancement after this got in place would be to support rendering it with the correct viewer (browser for html, notepad or something for text, etc.)

davidebb wrote Oct 9, 2010 at 1:55 AM

VS itself hosts IE's HTML engine, so I think by default that's how it would open a .htm file. Though personally, I prefer it it launches the default browser!

marcind wrote Oct 11, 2010 at 7:00 PM

I changed the title because I think my using readme.txt as an example steered people in the wrong direction.
Take a package that has some Setup.cs file deployed and a readme that says: "Go open Setup.cs and make a change to a line in there". What's the point of opening the readme file if the real actionable task is to open Setup.cs and make the change? You might as well open Setup.cs directly. That's the scenario i'm trying to target with this suggestion.
But this means that it has to be done via a package manifest annotation, rather then a naming convention (because the name should probably be something like MyPackageSetup.cs).

Haacked wrote Oct 12, 2010 at 5:29 AM

Ah, well that does make more sense. :)

Haacked wrote Oct 12, 2010 at 9:40 PM

Great idea, but not essential to v1.

Haacked wrote Jan 10, 2011 at 9:26 PM

We decided this is not the right experience for users. A package can depend on multiple others and having a whole swath of files suddenly opened can be confusing. You can always use Init.ps1 to open a file if you absolutely need to.

** Closed by Haacked 01/10/2011 2:26PM

Haacked wrote Sep 1, 2011 at 12:27 AM

Re-opening based on customer feedback.

Haacked wrote Sep 1, 2011 at 12:30 AM

Talked to the Glimpse guys and they've implemented this themselves using PowerShell. Not only that, they add the readmes to the project in App_Readme. If that catches on, we'll run into this problem anyways if other packages follow their lead.

The suggestion is that we have a convention for readme, say a top level "readme" folder in the package. BUT, we only open the root package. So if you install a package that depends on 10 others, we only open the readme for the one you explicitly installed. Kind of like the same logic we use to add packages to the Recent packages list.

davidebbo wrote Sep 1, 2011 at 1:14 AM

So you're saying we would not want those under Content, unlike what Glimpse is doing. Correct?

Haacked wrote Sep 1, 2011 at 1:43 AM

Yeah. I mean, correct me if you think I'm wrong, but I would think most folks wouldn't want their project littered with readmes, even if placed in an App_Readme folder. Instead, perhaps the convention is place a file named readme.txt in the root of your package. That way, you can still get back to the readme file because it's in the packages folder. And when we install the package, we just open the top level readme. AKA, the readme for the package that initiated the install.

Haacked wrote Sep 1, 2011 at 1:44 AM

Perhaps we allow README.txt, README.rtf, and README.html.

marcind wrote Sep 1, 2011 at 2:22 AM

I agree with not littering the project with readme files. Open them from the packages folder.

davidebbo wrote Sep 1, 2011 at 4:22 AM

Works for me. The downside is that the readme's in the Packages folder are a little hard to find since they're not in sln explorer. But still, it's better than littering the project with them.

And let's not forget to support readme.markdown!

nikmd23 wrote Sep 1, 2011 at 5:41 PM

As far as where Readme files are placed - the NuGet docs suggest using the conventions that Glimpse uses (Content/App_Readme). Perhaps this guidance should be changed or removed if we don't want this to catch on?

Here is the URL: http://docs.nuget.org/docs/creating-packages/package-conventions

davidebbo wrote Sep 1, 2011 at 6:03 PM

@nikmd23: good find. Evidently no one from the team remembered about this guidance from the doc! :) So yes, if we go with this new proposal, the guidance will change indeed.

nikmd23 wrote Sep 1, 2011 at 6:26 PM

Thanks @davidebb - if you do decide to move away from this convention, I've got the docs updated for you here: http://nugetdocs.codeplex.com/SourceControl/network/Forks/nikmd23/ConventionCleanup/contribution/1470

nikmd23 wrote Sep 1, 2011 at 6:37 PM

For those who do want to open a file when their NuPkg is installed, you can add the following script inside of your packages tools\install.ps1:

param($installPath, $toolsPath, $package, $project)

$path = [System.IO.Path]
$readmefile = $path::Combine($path::GetDirectoryName($project.FileName), "App_Readme\glimpse.readme.txt") #path to your important file here
$DTE.ItemOperations.OpenFile($readmefile)

davidebbo wrote Sep 1, 2011 at 7:10 PM

Great, thanks for sharing!

JeffHandley wrote Oct 11, 2011 at 9:12 PM

We will need to do this based on convention, and with a few restrictions:
1) The file must be named README.txt (case-insensitive)
2) The file must be placed at the root of the package, and not within the content folder or any other folder
3) We will only open the README.txt of the package that was directly installed, not those of any dependencies. We expect that package owners will roll-up the README content from dependencies into their own, adjusting as needed

We would only implement this for Visual Studio.

dotnetjunky wrote Oct 27, 2011 at 6:33 AM

Fixed in changeset 2cc225058a53

aldion wrote Jan 20, 2012 at 8:13 PM

[fixing note] using "Manage" to install to another project WON'T OPEN the readme.
I think this is ok since the readme has been previously opened.

pranavkm wrote May 4, 2012 at 12:28 AM

Fixed in changeset 776ef88e66c6

Sign in to add a comment