New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Good first PR] Add READMEs to undocumented plugins #7175

Open
mcornella opened this Issue Sep 30, 2018 · 61 comments

Comments

Projects
None yet
@mcornella
Copy link
Collaborator

mcornella commented Sep 30, 2018

Register at Hacktoberfest before submitting a Pull Request

Thank you to everyone who participated! You're free to continue on the quest to document all the plugins!


For some time we've had it in our minds to add a README to every plugin, as a way of documenting what the plugin does and what it requires, among other things. We have some READMEs already but most plugins lack one. That's why this issue exists, so you can take part in this effort.

You can have a look at existing plugin READMEs (the yarn README is a great example). Also you can find a Markdown guide here.

The README should follow a very simple structure:

  1. Name and brief description of what the plugin does. Links to relevant, essential websites.
    For example: the README for the ant plugin should link to the ant project.

  2. How to enable the plugin. You can just copy-paste the excerpt below and substitute the word PLUGIN for the name of the plugin:

    To use it, add PLUGIN to the plugins array of your zshrc file:
    ```
    plugins=(... PLUGIN)
    ```

  3. Any other sections that document what the plugin does. Examples of that are: a list of aliases, functions, or commands created; a description of settings that the plugin allows; how to build themes based on the plugin, ...

  4. Optionally: a section with a list of contributors.

You'll need to read the .plugin.zsh file to know what the plugin does or, if there isn't one, the plugin will probably just add completion. You can also get what the plugin does by looking at the commits, or even the plugins wiki.

If you want to work on the README for one of the following plugins, comment below and I'll mark it as such.

Thanks for your contribution and happy Hacktoberfest!

@heupr heupr bot added the bug label Sep 30, 2018

@D-sha

This comment has been minimized.

Copy link

D-sha commented Sep 30, 2018

I submitted a template to ease this process, what do you think?
#7028

@kashano

This comment has been minimized.

Copy link
Contributor

kashano commented Sep 30, 2018

I'll give it a shot to the gitignore and aws ones!

@grikomsn

This comment has been minimized.

Copy link
Contributor

grikomsn commented Sep 30, 2018

I submitted a template to ease this process, what do you think?
#7028

While having a template is great for most plugins, some doesn't even have any requirements or even configurations. Maybe if there's some kind of directory containing various readme templates for different kind of plugins, that'd be great.

Speaking of readmes, I have submitted a pull request about creating the readme for the sudo plugin (#7177).

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 1, 2018

I'll give it a shot to the gitignore and aws ones!

Reserved!

I have submitted a pull request about creating the readme for the sudo plugin

Thanks!

@grikomsn

This comment has been minimized.

Copy link
Contributor

grikomsn commented Oct 1, 2018

@mcornella, may I submit another pull request for other readmes? I'd love to complete two or more plugins. 😅

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 1, 2018

You can do as many as you like 😉

@Byte7

This comment has been minimized.

Copy link
Contributor

Byte7 commented Oct 1, 2018

I would like to do python and tmux plugins.

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 1, 2018

I would like to do python and tmux plugins.

Reserved

@alexandremjacques

This comment has been minimized.

Copy link
Contributor

alexandremjacques commented Oct 1, 2018

I can give a try on django plugin.

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 1, 2018

Reserved.

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 1, 2018

Don't hesitate to ask for directions!

@BrianMitchL

This comment has been minimized.

Copy link
Contributor

BrianMitchL commented Oct 2, 2018

I'll take the brew plugin

@denysdovhan

This comment has been minimized.

Copy link
Contributor

denysdovhan commented Oct 2, 2018

Hi 👋

I'd like to take grunt, gulp, node, nvm and web-search plugins. Please, mark them as reserved.

@zwhitten

This comment has been minimized.

Copy link
Contributor

zwhitten commented Oct 2, 2018

I'll take the mix plugin

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 2, 2018

I'd like to take grunt, gulp, node, nvm and web-search plugins. Please, mark them as reserved.

Done! For the web-search plugin you can get inspiration from the frontend-search plugin.

I'll take the mix plugin

Reserved.

@richardmoyer

This comment has been minimized.

Copy link
Contributor

richardmoyer commented Oct 2, 2018

in an effort to get involved in open source and learn git i have completed README's for tmuxinator, chucknorris, suse, common-aliases and rsync. i am unsure how to proceed from here.

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 2, 2018

in an effort to get involved in open source and learn git i have completed README's for tmuxinator, chucknorris, suse, common-aliases and rsync. i am unsure how to proceed from here.

Reserved. You can create the READMEs from the github web interface. For example, you'd navigate to the chucknorris folder and create a new file named README.md, and paste your README in the box.

image

Then you commit it (make sure to preview first to check that it looks nice), and afterwards it'll give you the option of creating a pull request.

More resources:

If you have made it using git, then this guide has a pretty comprehensive view of the steps you need to follow.

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 2, 2018

One README per Pull Request please.

@zwhitten

This comment has been minimized.

Copy link
Contributor

zwhitten commented Oct 2, 2018

I can also update Ubuntu

@mcornella

This comment has been minimized.

Copy link
Collaborator Author

mcornella commented Oct 2, 2018

I can also update Ubuntu

Reserved

@Byte7

This comment has been minimized.

Copy link
Contributor

Byte7 commented Oct 2, 2018

I can also update composer, debian, emoji-clock, pylint, virtualenv and pyenv. Please mar them as reserved.

@KaffDaddy

This comment has been minimized.

Copy link
Contributor

KaffDaddy commented Oct 19, 2018

Hi! For my first PR I would take the documentation of the gitignore-plugin. May you mark this as reserved for me? Thanks.

@ahaeber

This comment has been minimized.

Copy link
Contributor

ahaeber commented Oct 22, 2018

I've made PR #7325 with a brief description for the Helm plugin.

@dimensi0n

This comment has been minimized.

Copy link
Contributor

dimensi0n commented Oct 23, 2018

I'll do the REAMDE.md for symfony2 ^^

@kashano

This comment has been minimized.

Copy link
Contributor

kashano commented Oct 27, 2018

I'll take the kops one.

@kashano

This comment has been minimized.

Copy link
Contributor

kashano commented Oct 27, 2018

Also minikube.

seth-cohen pushed a commit to seth-cohen/oh-my-zsh that referenced this issue Oct 29, 2018

seth-cohen pushed a commit to seth-cohen/oh-my-zsh that referenced this issue Oct 29, 2018

akashfoss added a commit to akashfoss/oh-my-zsh that referenced this issue Oct 29, 2018

Updated Cabal plugin instructions
As per the maintainer, I have added a few more information regarding the plugin. Issue robbyrussell#7175 is fixed.

jmartindf added a commit to jmartindf/oh-my-zsh that referenced this issue Nov 10, 2018

jmartindf added a commit to jmartindf/oh-my-zsh that referenced this issue Nov 10, 2018

jefuba pushed a commit to jefuba/oh-my-zsh that referenced this issue Nov 19, 2018

jefuba pushed a commit to jefuba/oh-my-zsh that referenced this issue Nov 19, 2018

@dimensi0n

This comment has been minimized.

Copy link
Contributor

dimensi0n commented Dec 17, 2018

You need to tick þostgres plugin

@mcornella mcornella pinned this issue Jan 3, 2019

pawsen added a commit to pawsen/oh-my-zsh that referenced this issue Jan 19, 2019

pawsen added a commit to pawsen/oh-my-zsh that referenced this issue Jan 19, 2019

@jaythras

This comment has been minimized.

Copy link

jaythras commented Jan 28, 2019

Hi there! I will add the README for the git-prompt plugin.

jaythras added a commit to jaythras/oh-my-zsh that referenced this issue Jan 28, 2019

jaythras added a commit to jaythras/oh-my-zsh that referenced this issue Jan 28, 2019

akaralar added a commit to akaralar/oh-my-zsh that referenced this issue Feb 10, 2019

akaralar added a commit to akaralar/oh-my-zsh that referenced this issue Feb 10, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment