WIP - updates to README for 1.0.0 release #529

rkeithhill · 2018-01-13T23:03:48Z

I added a markdown linter to the list of recommended VSCode extensions. I cleaned up most of the linter warnings in the README. Still work to do here in terms of the branch/version listings. I'd also like to get the Travis URLs for the build table.

Completely open to suggestions here as I tweaked the format (mainly the beginning) just a bit.

dahlbyk · 2018-01-14T04:54:45Z

README.md

-## Versions
+### Build status
+
+| AppVeyor (Windows) | Travis (Linux) | Travis (macOS) | Code Coverage Status |


I don't believe it's possible to have separate Linux/macOS builds on Travis, so those columns could probably be combined.

That said, since there are subsections below for v0 and v1, I was thinking we could just put the build status for each right under their headings. This is as far as I got yesterday:

Also, tangent: Coveralls doesn't appear to support multiple/merged coverage reports, so we may want to use a different service if we wish to differentiate coverage by platform.

@rkeithhill did you have any thoughts on this? I am tentatively planning to pull the relevant parts from this PR into an update targeting master, before releasing v0.7.2.

dahlbyk · 2018-01-14T05:01:03Z

README.md

+PowerShell Core 6.x, both of which support writing prompt strings using [ANSI escape sequences][ansi-esc-code].
+On Windows, support for [Console Virtual Terminal Sequences][console-vt-seq] was added in Windows 10 version 1511.
+Consequently this version of posh-git introduces BREAKING changes with 0.x which including dropping support
+for Windows PowerShell version 2, 3 and 4 since these versions of PowerShell do not run on platforms that


Is it actually true that PowerShell pre-5 doesn't support prompts with ANSI escape sequences? I haven't tried, but I see no reason it wouldn't work with a proper host. Furthermore, 1.0 should still work on hosts without ANSI support.

It feels like you're blaming ANSI for the breaking changes, when they're mostly motivated (I think?) by improving the user experience (settings refactor) and making our lives easier dev-wise (newer languages features).

Well it is v5 (or v5.1) that adds the $host.UI.SupportsVirtualTerminal property we use to set the AnsiConsole setting. But I suppose someone could be using ConEmu or a shell like that. That said, posh-git 1.x won't run on anything less than v5 because of our use of PS classes.

RE blaming ANSI - I'm fine with rewording that to shift the emphasis to the settings restructuring.

dahlbyk · 2018-01-14T05:05:10Z

README.md

+
+### Active branches
+
+TODO: @dahlbyk Need to update for the new maintenance branch and moving v1 to master (and probably nuke develop, right?).  Maybe we integrate this info into the appropriate v0.x / v1.x sections above?


I've been pondering this. What if we just "renamed" master to v0, develop to v1, and started working with a v2 branch when the time comes? It would simplify "how do I link to v0's README?"-type questions, as well as targeting of PRs (is this change for v0 or v1?).

I was thinking you'd create a v0.x branch off of master, merge develop back to master and nuke develop for now. But you've got far more experience in this area than I. I'll defer to your judgement.

There's nothing special about master other than it being the repo's default branch, which we can change. I suppose it might mess with existing clones a bit if master disappeared, though.

I'll move forward with branch rearrangement as soon as v0.7.2 ships.

dahlbyk · 2018-01-14T05:08:42Z

README.md


-2. Script execution policy must be set to either `RemoteSigned` or `Unrestricted`.
+1. On Windows, script execution policy must be set to either `RemoteSigned` or `Unrestricted`.


Can these Markdown lint rules be tuned? One of the key objectives of Markdown is to be readable as plain text, so I prefer to use real numbering.

I also prefer inline links over reference links, especially for the CHANGELOG issue/PR links, though that preference isn't particularly strongly held.

Thoughts?

Yes, we can suppress md lint rules:

"markdownlint.config": { "MD013": false },

I was of the same opinion on the 1., 1., 1. lists but was eventually convinced that the vast majority will read it rendered and there's a benefit to not having to renumber (and keep numbering correct) on numbered lists. That said, I really had no choice - wasn't my repo and had to follow the rules. :-) I'm fine with suppressing this warning (or just living with squiggles in the md).

RE ref links, for a CHANGLELOG I definitely like inline. For README's I like having the links organized at the bottom - kind of like a bibliography. :-) Most of the other OSS projects I work on do it this way. But I can put it back to inline if you'd like.

As long as the linter won't complain about preferred style on all our (two) markdown files, I'm good. Reference links on readme is fine.

Updated the settings to not complain about numbered lists 1., 2., 3., etc and reverted the numbering change.

dahlbyk · 2018-01-14T05:09:15Z

README.md


 ```powershell
-PowerShellGet\Install-Module posh-git -Scope CurrentUser
+Install-Module posh-git -Scope CurrentUser -Force


-Force to get latest version?

To force side-by-side install. If you already have 0.7.1 installed, Install-Module will complain IIRC. Update-Module posh-git would work if you installed from the PSGallery. Or just use Install-Module with -Force.

WARNING: Version '0.7.1' of module 'posh-git' is already installed at 'C:\Users\Keith\Documents\WindowsPowerShell\Modules\posh-git\0.7.1'. To install version '1.0.0-beta1', run Install-Module and add the -Force parameter, this command will install version '1.0.0-beta1' in side-by-side with version '0.7.1'.

I'll defer to your experience here.

dahlbyk · 2018-01-14T05:10:15Z

README.md


-If you are on PowerShell version 3 or 4, you will need to install the [Package Management Preview for PowerShell 3 & 4](https://www.microsoft.com/en-us/download/details.aspx?id=51451) in order to run the command above.
+- If you are asked to trust packages coming from the PowerShell Gallery.


Could PowerShell Gallery troubleshooting tips be punted to a wiki page (here or a more canonical source)?

If we keep them here, this rephrased sentence should be joined to the following line with a comma.

Absolutely could punt. Wasn't sure about keeping this so I can be trivially talked into removing it. :-)

Since these are common hang-ups, and posh-git is often the only PS module a dev may have installed, I want to make sure guidance is available. Open to thoughts on where that would best live.

The trust issue is pretty common so I recommend we keep the troubleshooting help here.

dahlbyk · 2018-01-14T05:14:50Z

README.md

-[![develop build coverage](https://coveralls.io/repos/github/dahlbyk/posh-git/badge.svg?branch=develop)](https://coveralls.io/github/dahlbyk/posh-git?branch=develop)
-
-[![Join the chat at https://gitter.im/dahlbyk/posh-git](https://badges.gitter.im/dahlbyk/posh-git.svg)](https://gitter.im/dahlbyk/posh-git?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![posh-git on Chocolatey](https://img.shields.io/chocolatey/dt/poshgit.svg)](https://chocolatey.org/packages/poshgit/)


Was this intentionally dropped? I was thinking we'd add a PowerShell Gallery badge, too:

I added in the PSGallery badge. I had removed the Choco badge since the choco install instructions were removed.

I'm still leaning towards adjusting the Chocolatey installer for 1.x to wrap PowerShellGet, in which case I would suggest we keep basic instructions (with a note about it's relationship to PS Gallery) and the badge.

rkeithhill · 2018-01-18T03:49:07Z

@dahlbyk This needs some additional info on the updated $GitPromptSettings - also wanted to provide a link to https://www.w3schools.com/colors/colors_names.asp and discuss the additional Write-*Status commands. Did you already take this and modify it or is it OK for me to continue updating this PR?

dahlbyk · 2018-01-18T09:04:18Z

Did you already take this and modify it or is it OK for me to continue updating this PR?

Please continue, I won't have a chance to do much here until early next week.

rkeithhill · 2018-01-24T06:26:32Z

Getting close to being done on this. However, I'm wondering if we should use a few PNGs to display properly colored prompt text? Simply using the powershell syntax colorizer is not coloring properly. That said, I don't know if you want a half-dozen or so PNGs added to the repo. I guess we could put them in the Wiki and then link to them. Thoughts?

Another approach is to true to embed HTML style elements in the markdown file to get the right colors but I think that would likely make the markdown quite messy.

Add MD024 to markdown linter disable list. With CHANGELOG we have multiple headers with same name e.g. Added, Changed, Removed, Fixed.

rkeithhill · 2018-01-30T03:40:12Z

I think I'd like to drop in either a formatted text section or ideally a PNG in the Customization variables section:

Thoughts? The PNG file size is 137KB (and from beta1 - needs to be updated for beta2). We could put it in a doc\images dir or we could fudge and grab the blog URL for it from this issue (once it's updated).

As text it is less nice:

AnsiConsole                            : True
DefaultColor                           : ForegroundColor: <default>, BackgroundColor: <default>
BranchColor                            : ForegroundColor: �[106m  �[0m Cyan, BackgroundColor: <default>
IndexColor                             : ForegroundColor: �[42m  �[0m DarkGreen, BackgroundColor: <default>
WorkingColor                           : ForegroundColor: �[41m  �[0m DarkRed, BackgroundColor: <default>
StashColor                             : ForegroundColor: �[101m  �[0m Red, BackgroundColor: <default>
ErrorColor                             : ForegroundColor: �[101m  �[0m Red, BackgroundColor: <default>
BeforeText                             : Text: '�[93m [�[0m',	 ForegroundColor: �[103m  �[0m Yellow, BackgroundColor: <default>
...

rkeithhill · 2018-01-30T19:05:03Z

README.md

+[av-master-site]: https://ci.appveyor.com/project/dahlbyk/posh-git/branch/master
+[av-master-img]: https://ci.appveyor.com/api/projects/status/eb8erd5afaa01w80/branch/master?svg=true&pendingText=master%20%E2%80%A3%20pending&failingText=master%20%E2%80%A3%20failing&passingText=master%20%E2%80%A3%20passing
+
+[tv-develop-img]: https://travis-ci.org/dahlbyk/posh-git.svg?branch=develop


This link doesn't seem to be giving an updated/correct image. Image indicates failure but when you click on it, the page indicates success.

Curiously, Travis doesn't seem to support branch-specific links. travis-ci/travis-ci#5024

I'm expecting this link will be correct once v1 becomes the default branch here.

dahlbyk · 2018-02-04T21:10:36Z

I won't have a chance to do much here until early next week.

lol

I'm wondering if we should use a few PNGs to display properly colored prompt text? Simply using the powershell syntax colorizer is not coloring properly. That said, I don't know if you want a half-dozen or so PNGs added to the repo. I guess we could put them in the Wiki and then link to them. Thoughts?

Another approach is to true to embed HTML style elements in the markdown file to get the right colors but I think that would likely make the markdown quite messy.

An image of the expected prompt display, with appropriate alt text, seems reasonable. I agree that embedded HTML style would get too messy.

Including that same image in a wiki page, and letting GitHub host the image, seems preferable to including in the repo.

I think I'd like to drop in either a formatted text section or ideally a PNG in the Customization variables section…

Thoughts? The PNG file size is 137KB (and from beta1 - needs to be updated for beta2). We could put it in a doc\images dir or we could fudge and grab the blog URL for it from this issue (once it's updated).

As text it is less nice…

I'm content to have the more complete explanation of this on the wiki. And we should definitely strip any ANSI color sequences from the README.

rkeithhill · 2018-02-07T05:19:29Z

Take a look at the prompt images (first two). https://github.com/dahlbyk/posh-git/wiki/Customizing-Your-PowerShell-Prompt

They are a bit big due to me taking them on my high DPI monitor. Do you think these are too big?

rkeithhill · 2018-02-11T04:25:10Z

Hmm, I think I'm going to need to redo some of these images:

The DarkRed we use for the WorkingDir status is too dark. There is not enough contrast between it and the black background. This is the default/legacy color config I'm using (colortool cmd-legacy). Thoughts?

UPDATE: I think the issue is largely due to the fact that the web page has a whole lot of white. And that little swatch of black with DarkRed text doesn't look very good in that context. In the actual console, it doesn't look that bad to me. So for this image, I boosted the Red intensity from 128 to 192. The image above now reflects that change.

rkeithhill · 2018-02-12T16:42:01Z

BTW I think this README is close to being done. The tweaks that need to be made are in the version specific sections where we reference branches. And that only needs to change once we do the branch swaparoo.

dahlbyk · 2018-04-20T02:26:19Z

Waiting on this until v0.7.2 is out.

dahlbyk · 2018-05-05T22:17:16Z

Remove develop branch from build results

👍 can we add a row for v0 status? https://github.com/dahlbyk/posh-git/blame/v0/README.md#L20-L21

rkeithhill · 2018-05-05T22:18:15Z

Working on that right now.

rkeithhill · 2018-05-05T22:32:32Z

OK, I feel pretty good about this file now. The order of the sections is certainly debatable and should be easy to move around. But I "think" this is good enough to merge to master - unless you want me to re-order sections before we do that.

rkeithhill · 2018-05-05T23:37:53Z

One option is to perhaps re-order this:

- [Overview]
- [Git status summary information]
- [Customization variables]
- [Versions]
- [Installation]
- [Using posh-git]
- [Customizing the posh-git prompt]
- [Based on work by]

to

- [Overview]
- [Versions]
- [Installation]
- [Using posh-git]
- [Git status summary information]
- [Customization variables]
- [Customizing the posh-git prompt]
- [Based on work by]

Thoughts?

dahlbyk · 2018-05-06T02:50:56Z

I like this:

[Overview]
[Versions]
[Installation]
[Using posh-git]
[Git status summary information]
[Customization variables]
[Customizing the posh-git prompt]
[Based on work by]

There's a conflict with master, too.

rkeithhill · 2018-05-06T03:22:03Z

I made the re-order changes in PR #572. Seemed easier to just re-create the PR from a fresh branch off of master than to figure out the right commit to squash to.

WIP - updates to README for 1.0.0 release

9c37c76

rkeithhill requested a review from dahlbyk January 13, 2018 23:03

Add Travis build badge

31b0eb6

rkeithhill mentioned this pull request Jan 13, 2018

Travis badges #530

Closed

dahlbyk reviewed Jan 14, 2018

View reviewed changes

rkeithhill added 2 commits January 14, 2018 21:19

Address PR feedback

059d440

Add choco badge and remove Travis macOS placeholder

2466027

Add info on new ways to customize prompt

6f2902a

Trying a minor re-org with a TOC

32da673

Add MD024 to markdown linter disable list. With CHANGELOG we have multiple headers with same name e.g. Added, Changed, Removed, Fixed.

Fix section link

f63c68b

rkeithhill commented Jan 30, 2018

View reviewed changes

rkeithhill added 2 commits February 6, 2018 20:51

Merge branch 'develop' into rkeithhill/update-readme

6593edb

Try out images (from wiki)

5b33e90

rkeithhill added 2 commits February 10, 2018 16:56

Use images for prompt display

c60c7b2

Replace temp img urls w/actual urls

aaf8ab6

rkeithhill added 2 commits February 11, 2018 19:24

Remove working dir status from all but one prompt image

0606c27

Be clear that settings go after import command

a317ecb

rkeithhill added 4 commits February 18, 2018 14:36

Adjust for defaulting abbrev home dir to $true

ced492d

Promote prompt customization to 2nd level hdr, put in TOC

5896ed1

Fix paragraph in wrong place

7d188a7

Fix typo - variale -> variable

1d6fe0c

rkeithhill mentioned this pull request Feb 20, 2018

Roadmap to 1.0 #328

Open

13 tasks

rkeithhill added 2 commits April 15, 2018 13:11

Merge branch 'develop' into rkeithhill/update-readme

a1d4116

Update for setting name change - Middle -> BeforeSuffix

e2d67a0

dahlbyk added this to the v1.0 milestone Apr 20, 2018

dahlbyk mentioned this pull request Apr 20, 2018

Release v0.7.2 #522

Merged

dahlbyk changed the base branch from develop to master April 20, 2018 05:32

rkeithhill added 3 commits May 5, 2018 15:19

Remove develop branch from build results

460094f

Change DefaultPromptMiddle to DefaultPromptBeforeSuffix

e2ba32b

More wording/markdown cleanup

0602cc8

Adopt "Versions" section from master README

9f56670

rkeithhill mentioned this pull request May 6, 2018

Update README.md for v1.0.0 release #572

Merged

rkeithhill closed this May 6, 2018

rkeithhill deleted the rkeithhill/update-readme branch May 14, 2018 03:36


		### Active branches

		TODO: @dahlbyk Need to update for the new maintenance branch and moving v1 to master (and probably nuke develop, right?). Maybe we integrate this info into the appropriate v0.x / v1.x sections above?


		2. Script execution policy must be set to either `RemoteSigned` or `Unrestricted`.
		1. On Windows, script execution policy must be set to either `RemoteSigned` or `Unrestricted`.


		If you are on PowerShell version 3 or 4, you will need to install the [Package Management Preview for PowerShell 3 & 4](https://www.microsoft.com/en-us/download/details.aspx?id=51451) in order to run the command above.
		- If you are asked to trust packages coming from the PowerShell Gallery.

WIP - updates to README for 1.0.0 release #529

WIP - updates to README for 1.0.0 release #529

Conversation

rkeithhill commented Jan 13, 2018

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

dahlbyk Jan 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rkeithhill commented Jan 18, 2018

dahlbyk commented Jan 18, 2018

rkeithhill commented Jan 24, 2018

rkeithhill commented Jan 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dahlbyk commented Feb 4, 2018

rkeithhill commented Feb 7, 2018

rkeithhill commented Feb 11, 2018 • edited Loading

rkeithhill commented Feb 12, 2018

dahlbyk commented Apr 20, 2018

dahlbyk commented May 5, 2018

rkeithhill commented May 5, 2018

rkeithhill commented May 5, 2018

rkeithhill commented May 5, 2018 • edited Loading

dahlbyk commented May 6, 2018

rkeithhill commented May 6, 2018

dahlbyk Jan 14, 2018 •

edited

Loading

rkeithhill commented Jan 30, 2018 •

edited

Loading

rkeithhill commented Feb 11, 2018 •

edited

Loading

rkeithhill commented May 5, 2018 •

edited

Loading