Documentation improvement - Help wanted!

[pvdlg]

Most of the documentation has been rewritten recently. The content minimum content we need is there but there is a lot that can be done to improve it.

If you'd like to contribute to the semantic-release project, helping with the following would be much appreciated:

• Fix typo, misspelling and gramatical mistakes
• Improve language: make short and simpler sentences, improve clarity
• Harmonize the style and format, especially regarding code quote, markdown table, capitalization of brands, links

See CONTRIBUTING.md#documentation for all the details.

All the repository in the semantic-release organization need some improvement regarding the documentation!

Thanks!

[ts-npm]

I could help with this.

[gr2m]

Pull requests welcome :) Thanks for your help!

[whosford]

I have a question about the dryRun configuration documentation. It states the following for the default value.

Default: false if running in a CI environment, false otherwise

This makes it sound as though the default is always false, is this correct?

[gr2m]

yes, I think that should be

Default: false if running in a CI environment, true otherwise

But maybe double check the code to make sure :)

[EfstathiadisDimitris]

Do you guys still need help. I can jump on this in the weekend..

[pvdlg]

@EfstathiadisDimitris yes, I think the documentation can always be improved. I wrote most of the doc and I'm not a native English speaker not a good documentation writer in general.
So help would be greatly appreciated. A lot of doc has been added recently on the beta branch, so you might want to look at that as it's probably what needs the most improvements.

[ray1981jacob]

Is anything else know if I need to do

[JoA-MoS]

I saw commitizen was removed in #1255 the contributing guide still references this as well as an npm script that doesn't exist. What guidelines do you want to provide contributors? Should it just say use the Angular Commit conventions and link to that page?

[pvdlg]

The paragraph https://github.com/semantic-release/semantic-release/blob/master/CONTRIBUTING.md#commits should be just removed. The rest of the doc details the convention already.

[seeliang]

do we have a document about how to make beta branch generate beta build?

[pvdlg]

Yes:

• https://github.com/semantic-release/semantic-release/blob/beta/docs/usage/workflow-configuration.md#workflow-configuration
• https://github.com/semantic-release/semantic-release/tree/beta/docs/recipes#release-workflow

[seeliang]

@pvdlg , thanks, great doc, somehow it is not indexed by google, shame

[edmundo096]

Not sure but there may be an order error on an example given on https://github.com/semantic-release/semantic-release/blob/master/docs/usage/plugins.md#plugins-declaration-and-execution-order

The list currently has

• execute the verifyConditions implementation of @semantic-release/npm then @semantic-release/git
• execute the analyzeCommits implementation of @semantic-release/commit-analyzer
• execute the prepare implementation of @semantic-release/npm then @semantic-release/git
• execute the generateNotes implementation of @semantic-release/release-notes-generator
• execute the publish implementation of @semantic-release/npm

but as far I can understand according the steps defined on the top of the doc, generateNotes should go before prepare.

May not be a good place to comment it but better somewhere than missing it for later.