docs: improve README & Contribution guidelines #11178

ncoden · 2018-04-15T20:44:47Z

Changes:

739b095 Improve README design & organization
cc5ffdb replace "Yetinauts" mentions by "Core Team"
cdaefe6 improve issues & PR recommendation in CONTRIBUTE.md
ea46f49 improve GitHub issue template
368e8e3 improve GitHub pull request template
aae8d71 improve GitFlow documentation in CONTRIBUTING.md
... various typo fixes...

Preview:

Changes * Add Foundation logo * Add menu bar with installation/docs/releases/contributing * Simplify local running & testing sections

ncoden · 2018-04-18T20:45:55Z

Poke @DanielRuf @IamManchanda for review ;)

This template was generated by https://www.talater.com/open-source-templates/#/ and modified according to our own CONTRIBUTION.md guidelines.

ncoden · 2018-04-20T20:48:10Z

ea46f49 chore: improve GitHub issue template
368e8e3 chore: improve GitHub pull request template

@DanielRuf @IamManchanda Templates are now a bit less "friendly" but much mure useful for someone that don't know very well the GitHub conventions and practices to submit a good issue or pull request. Let me know what you think ;)

Also, we now require an approving review for every single pull request. So this pull request will never be merged without your review ;)

DanielRuf · 2018-04-20T21:50:55Z

Sounds good, will do a review this weekend. 👍

ncoden · 2018-04-20T22:59:55Z

aae8d71 docs: improve gitflow documentation in CONTRIBUTING.md

I fixed some typo mistakes and improved the formatting and formulations.

Changes: * limite lines lenght to 80 characters * add centering and left/right alignement of texts * use `-` instead of `*` for lists

ncoden · 2018-04-20T23:51:26Z

6419b6c chore: improve GitHub templates readibility in text format

Before:

After:

…template

DanielRuf

Just a few things which can be improved.

Much better templates and docs, really great =)

DanielRuf · 2018-04-21T19:23:40Z

.github/ISSUE_TEMPLATE.md

+<!---                 Please fill the following template                    -->
+<!---                 Your issue may be ignored otherwise                   -->
+<!--- --------------------------------------------------------------------- -->
+<!---  Only submit here bug or feature requests. For help or questions to   -->


here bug or feature requests => bug or feature requests here (sounds a bit better)

DanielRuf · 2018-04-21T19:25:09Z

.github/ISSUE_TEMPLATE.md

+<!---                 Your issue may be ignored otherwise                   -->
+<!--- --------------------------------------------------------------------- -->
+<!---  Only submit here bug or feature requests. For help or questions to   -->
+<!---  the community, see the forum: https://foundation.zurb.com/forum      -->


"to the community", I'm thinking there is a verb missing (submit or a better one?)

Isn't "for questions to the community" valid ?
It can be "for questions for the community" too.

The context gets a bit spread / lost because of this but I'm fine if we keep it like it is.

Adding a verb = no place left to keep that on 2 lines 😅

DanielRuf · 2018-04-21T19:25:40Z

.github/ISSUE_TEMPLATE.md

+<!--- or ideas how to implement the addition or change.                     -->
+
+## Test Case and/or Steps to Reproduce (for bugs)
+<!--- We highly recommand you to provide a live example of your bug so we   -->


recommand => recommend

DanielRuf · 2018-04-21T19:27:24Z

.github/ISSUE_TEMPLATE.md

+<!--- Include as many relevant details about the context and environment    -->
+<!--- you experienced the bug in. You can also provide logs.                -->
+- Foundation version(s) used:
+- Browser(s) Name and version(s):


Name => name

What about the npm / yarn and Node.js (webpack and so on) version? Is this covered by the project link?

I think there is only a few rare cases when we need them (like for build issue). No need to ask for them in every issue.

You are right.

DanielRuf · 2018-04-21T19:28:44Z

.github/ISSUE_TEMPLATE.md

+<!--- If you're unsure about any of these, don't hesitate to ask.           -->
+- [ ] I have read and follow the [CONTRIBUTING](CONTRIBUTING.md) document.
+- [ ] This is a bug report or a feature request.
+- [ ] There is no other issues similar to this one.


There is => There are

DanielRuf · 2018-04-21T19:45:44Z

CONTRIBUTING.md

- **`master`**: The stable branch. It only contains the latest stable version released. Do NOT open pull requests on it.
- **`develop`**: The developing branch is used to prepare the next minor/major version. It always contains all the new features and bug fixes, and is the most up-to-date version of Foundation. Almost every pull request should be opened on this branch (fixes, features, documentation...). When a new version is released, it is merged on `master`, a support branch is created, and `develop` now targets the next version.
- **`support/*`**: Support branches are used to support the previous versions (i.e. `support/v6.5` for `v6.5.0`) and prepare patches (i.e. `v6.5.1`). When a pull request for a bug fix is merged on `develop` and is compatible with supported versions, its commits must be added on the compatible `support/*` branches too. A patch version can be then released. If a fix is not compatible with `develop`, a pull request can be opened on the latest compatible and supported `support/*` branch.
+Foundation uses a git workflow close to the the successful [GitFlow](http://nvie.com/posts/a-successful-git-branching-model/) branching model, to which we added "support" branches to be able to release patches for older Foundation versions. Most of the time you will not have to care about this workflow and can simply open your pull request on `develop`.


git workflow => Git workflow

DanielRuf · 2018-04-21T19:48:39Z

CONTRIBUTING.md


-Want to join our crack team of Yetinauts? The Core Team is inviting active community members to become Yetinauts  on a case-by-case basis. If you want to become a contributor, engage the community on the Foundation Forum, help us close issues on GitHub, and review pull requests from other contributors.
+Want to help us making Foundation the best framework ever? The Core Team is inviting active community members join it. If you want to become a contributor, engage the community on the Foundation Forum, help us close issues on GitHub, and review pull requests from other contributors.


join it => to join it

DanielRuf · 2018-04-21T19:49:17Z

README.md

-# [Foundation for Sites](http://foundation.zurb.com)
+<p align="center">
+  <a href="http://foundation.zurb.com/">
+    <img src="https://user-images.githubusercontent.com/9939075/38782856-2a64a43e-40fa-11e8-89cd-e873af03b3c4.png" alt="Foundation for Sites 6" width="50%"/>


Could need a min-width for the mobile GitHub site / design.

I set a full width with a max width instead, so it does not break on even smaller mobiles.

Perfect 👍

Hmm actually inline styles are removed by GitHub. So I guess all we can do is setting width="50%" or width="384px". What do you prefer ?

The px value should be better. Not sure but in one project I got it working with the owners (responsive styles).

Can you remember what project it was ?

It was airbnb/react-sketchapp#249
https://github.com/airbnb/react-sketchapp/pull/249/files

Interesting, the currently generated markup is <img alt="react-sketchapp" src="https://camo.githubusercontent.com/7a75c94cd088b6ae393cc2648d6d7f9a45ff0b5a/68747470733a2f2f636c6475702e636f6d2f4d785356456b635f67622e706e67" data-canonical-src="https://cldup.com/MxSVEkc_gb.png" style="max-width:100%;"> so it seems like a bug to me on the side of GitHub which removes all inline rules if there are more than one.

style="max-width:100%;" with the right natural maximum dimensions should still work.

It works. Thanks.

DanielRuf · 2018-04-21T19:50:54Z

README.md


 [![Build Status](https://travis-ci.org/zurb/foundation-sites.svg?branch=develop)](https://travis-ci.org/zurb/foundation-sites)
+[![dependencies Status](https://david-dm.org/zurb/foundation-sites/status.svg)](https://david-dm.org/zurb/foundation-sites)


Not sure if shields.io would be better https://shields.io/

I did not know this website. It looks awesome. Why would it be better ?

Because shields.io provides (cached) badges for many of these solutions through one url =)

This should be done for all badges then. And we could talk about what badges are really useful. Will do this later in an other PR.

DanielRuf · 2018-04-21T19:53:55Z

README.md

@@ -54,4 +67,8 @@ Testing Supported By<br/>

 Check out [CONTRIBUTING.md](CONTRIBUTING.md) to see how to report an issue or submit a bug fix or a new feature, and our  [contributing guide](http://foundation.zurb.com/develop/contribute.html) to learn how you can contribute more globally to Foundation. You can also browse the [Help Wanted](https://github.com/zurb/foundation-sites/labels/help%20wanted) tag in our issue tracker to find things to do.

+## Training
+
+Want the guided tour to Foundation from the team that built it? The ZURB team offers comprehensive training courses for developers of all skill levels. If you're new to Foundation, check out the [Introduction to Foundation Course](http://zurb.com/university/foundation-intro?utm_source=Github%20Repo&utm_medium=website&utm_campaign=readme&utm_content=readme%20training%20link) to kickstart your skills, amplify your productivity, and get a comprehensive overview of everything Foundation has to offer. More Advanced users should check out the [Advanced Foundation Course](http://zurb.com/university/advanced-foundation-training?utm_source=Github%20Repo&utm_medium=website&utm_campaign=readme&utm_content=readme%20training%20link) to learn the Advanced skills that ZURB uses to deliver quality client work in short timeframes.


Advanced => advanced

As there are things to do and not done, they should not be pre-checked.

ncoden · 2018-04-21T20:36:34Z

Thanks for the review @DanielRuf and sorry for all the typo mistakes.

ncoden · 2018-04-21T21:01:22Z

@DanielRuf In addition to the typo mistakes, do you have any opinion or recommendation about the global content of the README/CONTRIBUTING files and GitHub templates ? Something to change or add ?

GitHub remove all inline styles but `max-width: 100%`

ncoden · 2018-04-21T21:25:15Z

@DanielRuf Everything is fixed.

DanielRuf · 2018-04-21T21:29:04Z

@DanielRuf In addition to the typo mistakes, do you have any opinion or recommendation about the global content of the README/CONTRIBUTING files and GitHub templates ? Something to change or add ?

They are great so far and better structured, nothing really to add or change at the moment / so far.

ncoden · 2018-04-21T21:30:09Z

Nice. Thank you for the review.

…-contribution-guidelines for v6.5.0 739b095 docs: improve README design & organization cc5ffdb docs: replace "Yetinauts" mentions by "Core Team" cdaefe6 docs: improve issues & PR recommendation in CONTRIBUTE.md 423e770 docs: fix lists formatting in CONTRIBUTING.md 4ffab21 docs: fix link to CONTRIBUTING.md in README ffa24b8 docs: fix internals links in CONTRIBUTING.md 94f9c70 docs: fix typo in Contributions section of CONTRIBUTING.md ea46f49 chore: improve GitHub issue template 368e8e3 chore: improve GitHub pull request template aae8d71 docs: improve gitflow documentation in CONTRIBUTING.md 6419b6c chore: improve GitHub templates readibility in text format 9521d07 chore: simplify the description explainaition in GitHub pull request template 720815e chore: add checkbox aobut commits in GitHub pull request template 5e3c998 chore: make the user "follow" CONTRIBUTING.md and not simply read it 7516d9a docs: fix various typo in contribution recommendations 9e34d29 docs: improve README logo responsivness efc4a12 chore: uncheck TODO lists in CONTRIBUTING.md 0067276 docs: fix typo in CONTRIBUTING.md afc13ab docs: fix README logo inline styles for GitHub Signed-off-by: Nicolas Coden <nicolas@ncoden.fr>

docs: improve README design & organization

739b095

Changes * Add Foundation logo * Add menu bar with installation/docs/releases/contributing * Simplify local running & testing sections

ncoden added 📖 documentation WIP labels Apr 15, 2018

ncoden added 2 commits April 18, 2018 22:09

docs: replace "Yetinauts" mentions by "Core Team"

cc5ffdb

docs: improve issues & PR recommendation in CONTRIBUTE.md

cdaefe6

ncoden force-pushed the docs/improve-reedme-and-contribution-guidelines branch from 74790c4 to 8b387a6 Compare April 18, 2018 20:32

docs: fix lists formatting in CONTRIBUTING.md

423e770

ncoden force-pushed the docs/improve-reedme-and-contribution-guidelines branch from 8b387a6 to 423e770 Compare April 18, 2018 20:34

ncoden changed the title ~~[WIP] docs: improve README & Contribution guidelines~~ docs: improve README & Contribution guidelines Apr 18, 2018

ncoden requested review from DanielRuf and IamManchanda April 18, 2018 20:37

ncoden added 3 commits April 18, 2018 22:40

docs: fix link to CONTRIBUTING.md in README

4ffab21

docs: fix internals links in CONTRIBUTING.md

ffa24b8

docs: fix typo in Contributions section of CONTRIBUTING.md

94f9c70

ncoden added 2 commits April 20, 2018 22:38

chore: improve GitHub issue template

ea46f49

This template was generated by https://www.talater.com/open-source-templates/#/ and modified according to our own CONTRIBUTION.md guidelines.

chore: improve GitHub pull request template

368e8e3

This template was generated by https://www.talater.com/open-source-templates/#/ and modified according to our own CONTRIBUTION.md guidelines.

docs: improve gitflow documentation in CONTRIBUTING.md

aae8d71

chore: improve GitHub templates readibility in text format

6419b6c

Changes: * limite lines lenght to 80 characters * add centering and left/right alignement of texts * use `-` instead of `*` for lists

ncoden added 3 commits April 21, 2018 12:25

chore: simplify the description explainaition in GitHub pull request …

9521d07

…template

chore: add checkbox aobut commits in GitHub pull request template

720815e

chore: make the user "follow" CONTRIBUTING.md and not simply read it

5e3c998

DanielRuf suggested changes Apr 21, 2018

View reviewed changes

ncoden added 3 commits April 21, 2018 22:26

docs: fix various typo in contribution recommendations

7516d9a

docs: improve README logo responsivness

9e34d29

chore: uncheck TODO lists in CONTRIBUTING.md

efc4a12

As there are things to do and not done, they should not be pre-checked.

ncoden force-pushed the docs/improve-reedme-and-contribution-guidelines branch from 53d3a46 to efc4a12 Compare April 21, 2018 20:41

ncoden added 2 commits April 21, 2018 23:03

docs: fix typo in CONTRIBUTING.md

0067276

docs: fix README logo inline styles for GitHub

afc13ab

GitHub remove all inline styles but `max-width: 100%`

ncoden removed the WIP label Apr 21, 2018

DanielRuf approved these changes Apr 21, 2018

View reviewed changes

ncoden merged commit ed2e2fb into foundation:develop Apr 22, 2018

This was referenced Jun 16, 2018

🚀 Release v6.5.0-rc.1 #11340

Merged

fix: keep a scrollbar on document when Reveal opens #7831 #11341

Merged


		Want to join our crack team of Yetinauts? The Core Team is inviting active community members to become Yetinauts on a case-by-case basis. If you want to become a contributor, engage the community on the Foundation Forum, help us close issues on GitHub, and review pull requests from other contributors.
		Want to help us making Foundation the best framework ever? The Core Team is inviting active community members join it. If you want to become a contributor, engage the community on the Foundation Forum, help us close issues on GitHub, and review pull requests from other contributors.


		[![Build Status](https://travis-ci.org/zurb/foundation-sites.svg?branch=develop)](https://travis-ci.org/zurb/foundation-sites)
		[![dependencies Status](https://david-dm.org/zurb/foundation-sites/status.svg)](https://david-dm.org/zurb/foundation-sites)

docs: improve README & Contribution guidelines #11178

docs: improve README & Contribution guidelines #11178

Conversation

ncoden commented Apr 15, 2018 • edited Loading

Changes:

Preview:

ncoden commented Apr 18, 2018

ncoden commented Apr 20, 2018

DanielRuf commented Apr 20, 2018

ncoden commented Apr 20, 2018 • edited Loading

ncoden commented Apr 20, 2018

DanielRuf left a comment • edited Loading

Choose a reason for hiding this comment

DanielRuf Apr 21, 2018 • edited Loading

Choose a reason for hiding this comment

DanielRuf Apr 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DanielRuf Apr 21, 2018 • edited Loading

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

ncoden Apr 21, 2018 • edited Loading

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

ncoden commented Apr 21, 2018

ncoden commented Apr 21, 2018

ncoden commented Apr 21, 2018

DanielRuf commented Apr 21, 2018

ncoden commented Apr 21, 2018

ncoden commented Apr 15, 2018 •

edited

Loading

ncoden commented Apr 20, 2018 •

edited

Loading

DanielRuf left a comment •

edited

Loading

DanielRuf Apr 21, 2018 •

edited

Loading

DanielRuf Apr 21, 2018 •

edited

Loading

DanielRuf Apr 21, 2018 •

edited

Loading

ncoden Apr 21, 2018 •

edited

Loading