Additions/Edits to make README.md more beginner-friendly

[adriennelim]

Whilst the current README.md guide provided a lot of good info, I encountered several issues while following the step by step guide. Following a brief discussion with Anya, here is a list of improvement opportunities identified:

a) Add step to cd into local forked repo before proceeding to next installation steps.

b) Add note to explain that if already running a newer version of Ruby and there may be a need to install 2.3.1 in order to switch to the older version before proceeding with other installation steps.

c) Add section to explain how to run site locally (step by step guide & tips). Cover case there if already had worked on a project before and want to contribute again.

d) Add section to explain GitHub workflow (step by step guide & tips) e.g.

• how to submit new issue (bug/feat)
• how to make pull requests
• work on branches (not master!)
• switching to another branch if fixing multiple issues

e) Add a list of topics in the beginning with links to different sections of the Readme for easier discovery and navigation. Here's an example.

[adriennelim]

Related issue: #148 Add jshint.

[adriennelim]

Can I give it a go to solve (a), (b), (d) & (e), please? :)

[cherchezlafemme]

We need to define the new updated structure of readme here, before starting to work on this. Let's start with this as a draft:

• About she's coding (exist already)
• Environment set up (that will include installation steps for package managers, ruby + rails) - (need work, some exist, need new information)
  • need to add a step to see what you already have. before starting to install things, we need to check if you already have rbenv or rvm, what ruby version you have. a step to define base line for the environment set up.
  • need to be explicit that you don't need 2 package managers, you only need one. If you have rvm, do this (and do not install rbenv as well) - we need a god way to visually show that.
• Database set up: Section about database set up.need provide more context on why we do this. (exist already, minor edits)
• How to run locally steps (explain what rails s means, why we do bundle install and when you need to do it (say, new package was added), add a noteto open second terminal for git workflow, since server should be running in the first one once rails s is executed. stopping the server stops the local copy of site) (some exist already, need edits)
• How to run tests and why we do this (exist already, minor edits)
• How to run jshint linter and when to do this (new information)

// Need write content for 3 new extra useful section to help first time contributors

• Project structure overview: Explain the project structure - how to find a view or a controller or css (new information)
• Section on available code editors (can be helpful if that's first project) (new information)
• GitHub workflow (includes the list of subtopics @adriennelim listed under d)) (new information)

Does this sound reasonable? Readme should be able to cover:

1. What she's coding is about
2. Asses your environment
3. Set up environment based on results of 2
4. Start database sever
5. Launch project locally - see copy of the site
6. Have reference on how to work in branches (made clear to work in feature branch not master)
7. Know how to open a PR and how to open an issue; know what to expect once you open a PR
8. How to find a file you should be editing (make you familiar with project structure)

[Elenaires]

Nice work @adriennelim and @cherchezlafemme ! I have a question about setting up our local repo. In README.md, the instruction says to clone the repository by git clone https://github.com/shescoding/shescoding-dot-org.git However, if I do that, I will not be able to push my changes to it i.e. doing git push origin <branchname> will result in an error "fatal: unable to access 'https://github.com/shescoding/shescoding-dot-org.git/': The requested URL returned error: 403"

Upon further research, it seems to me that we are supposed to create a clone of our fork instead of a clone of the original repo i.e. git clone https://github.com/YOUR-USERNAME/shescoding-dot-org.git see step 2 in https://help.github.com/articles/fork-a-repo/

I wonder if my understanding is correct or if the instruction in README.md needs to be updated? :)

[cherchezlafemme]

Need to include information on "How to name a PR" and "What to put in description of PR" + "How to reference the issue the PR is addressing".

[adriennelim]

Hello Anya et al,

Apologies, I won't be able to complete this task due to increased workload. Can you change the status so that it's up for grabs for others?

Thanks & sorry!

[adriennelim]

Closed this by accident - reopening now.

[cherchezlafemme]

no problem @adriennelim thank you so much for letting us know! ❤️