Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Update Contributing.md #1645

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.

Sign up for GitHub

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

Merged
merged 6 commits into from
Jan 9, 2020
Merged

Update Contributing.md #1645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
50a91a1
Update Contributing.md
Jan 4, 2020
7bd0d57
typo fixup
Jan 8, 2020
570598a
typo fixup
Jan 8, 2020
7442da9
edits
Jan 8, 2020
d133725
change URL
Jan 9, 2020
bb91457
change URL
Jan 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 79 additions & 51 deletions Contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,119 @@
# Repo Organization
# Contributing to Plotly's Graphing Libraries Documentation

Edit or add files in the `_posts` folder in the [source-design-merge](http://github.com/plotly/documentation/tree/source-design-merge) branch.
## Repo Overview

## Clone the Repo and Install Dependencies
Plotly welcomes contributions to its [open-source graphing libraries documentation](https://plot.ly/graphing-libraries) from its community of users.

1. Clone the repo and then check out the source-design-merge branch:
This repository mainly serves:
- Plotly's graphing libraries documentation index page at https://plot.ly/graphing-libraries.

- Plotly's JavaScript graphing library documentation at https://plot.ly/javascript
- Please be aware that **only the content of Plotly's JavaScript graphing library documentation** (hosted at https://plot.ly/javascript) is contained in this repository. You can find the content in the `_posts/plotly_js` directory.
- For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/source-design-merge/_posts/plotly_js/README.md).

- Plotly's Python graphing library documentation at https://plot.ly/python
- The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time.
- For information about editing **plotly.py** documentation [click here](https://github.com/plotly/plotly.py/blob/master/doc/README.md).

- Plotly's R graphing library documentation at https://plot.ly/r
- The content for Plotly's R graphing library documentation (hosted at https://plot.ly/r) **IS NOT** contained in this repository. It is contained in the `plotly.r-docs` repository at https://github.com/plotly/plotly.r-docs/ and is cloned into this repository at build time.
- For information about editing Plotly's **R** documentation [click here](https://github.com/plotly/plotly.r-docs/blob/master/README.md).

## Contribute Quickly to Plotly's JavaScript Graphing Library Documentation

To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest.

The easiest way to do this is to follow the `Edit this page on GitHub` link at the top right of the page you are interested in contributing to:

![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)

**Note:** You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request.

## How To Get The Application Working Locally

For more extensive changes to Ploty's JavaScript documentation, we suggest getting the Jekyll application which builds the site to run locally so that you can test your changes as you develop them.

This involves cloning the repository and installing its dependencies: [Git](https://git-scm.com/), [Ruby]((https://www.ruby-lang.org/en/), [Jekyll](https://jekyllrb.com/), and the [Python `requests` package](https://pypi.org/project/requests/).

1. Use [`git`](https://git-scm.com/) to [clone](https://git-scm.com/docs/git-clone) the public `plotly/documentation` repository. Then [check out] (https://git-scm.com/docs/git-checkout) the source-design-merge branch of the `git` repository.

To do so, run the following commands in your terminal:

```sh
git clone [email protected]:plotly/documentation.git
git fetch origin
git checkout source-design-merge
```

2. Check Ruby version `$ ruby --version`. We recommend using `version 2.3.3` or the same ruby version as [gh-pages](https://pages.github.com/versions/). Note [RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions.
**Note:** For historical reasons, the `source-design-merge` branch is the `master` branch of this repository.

3. Install bundler and dependencies from the `Gemfile`:
Running `git status` in your terminal should then output the following:

```sh
gem install bundler
bundle install
On branch source-design-merge
Your branch is up to date with 'origin/source-design-merge'.

nothing to commit, working tree clean
```

Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using.
2. Download Ruby and check your `Ruby` version by running the `ruby --version` command in your terminal.

4. When we deploy, a function is run to update the plot schema. To do this successfully you have to make sure you have the `requests` python package: `pip install requests`
**Note:** We recommend using `version 2.3.3` or the same ruby version as [gh-pages](https://pages.github.com/versions/). Note [RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions.

## Making Changes
3. Download Jekyll and check your Jekyll version by running the `jekyll -v` command in your terminal. We recommend using the same ruby version as [gh-pages](https://pages.github.com/versions/).

- For information about editing **plotly.js** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/plotly_js/README.md
- For information about editing **python** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/python/README.md
- For information about editing **R** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/r/README.md
- For information about editing chart studio documentation found at [https://help.plot.ly/tutorials/](https://help.plot.ly/tutorials/) please see this repo: [https://github.com/plotly/plotly.github.io](https://github.com/plotly/plotly.github.io)
4. Install bundler and dependencies from the Jekyll applicaton's [`Gemfile`](https://github.com/plotly/documentation/blob/source-design-merge/Gemfile) by running the following commands in your terminal:

```sh
gem install bundler
bundle install
```

## Render Changes Locally
**Note:** These dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using.

Please **ALWAYS** locally serve the docs and check your changes before committing updates.
5. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.

1. To serve the docs locally, in the documentation repo run: `bundle exec jekyll serve --config _config_dev.yml`
2. Visit the pages at: [http://localhost:4000/python/](http://localhost:4000/python/)
3. When you make changes, jekyll should automatically regenerate for you. Read the messages in your terminal to check it out
6. Visit the pages at: [http://localhost:4000/](http://localhost:4000)

There are a TON of posts in here, so rendering can take up to
thirty minutes! You can *limit* the number of posts that render by
excluding folders in the `_config_dev.yml` file.
**Note** The default Jekyll configuration file only builds the JavaScript posts by [excluding folders](https://jekyllrb.com/docs/configuration/options/). If you want to override this behavior, serve the application with a custom Jekyll configuration file in the root of the repository. Do this by copying `_config_dev.yml`, renaming it `_config_personal.yml`, and modifying the `exclude` statement.

For example, change `_config_dev.yml` to this:
- If you name the Jekyll configuration file `_config_personal.yml`, it will be caught by the `.gitignore` file and not committed to version control.
- Run `bundle exec jekyll serve --config _config_personal.yml` to use the custom configuration file

- Example configuration:
```yml
staticurl: http://localhost:4000/all_static
exclude: [_posts/ggplot2, _posts/julia, _posts/matlab, _posts/matplotlib, _posts/nodejs, _posts/r] # [_posts/python,]
# ---
# Excludes every directory except JavaScript
# ---
exclude: ['_posts/reference_pages', _posts/ggplot2','_posts/julia','_posts/matlab','_posts/node_js','_posts/r','_posts/python','_posts/python-v3','_posts/misc','_posts/dashboards',_posts/scala', '_posts/nodejs', 'node_modules']
```

and you'll only load the files in `_posts/python`.
and you'll only load the files in `_posts/plotly_js` directory because that is the only directory that is not excluded.

Change it to this
Change it to this:

```yml
# ---
# Excludes no directory
# ---
staticurl: http://localhost:4000/all_static
exclude: []
```

and it'll load everything.

## Make a PR
Ready for your changes to be reviewed? Make a pull request against the `source-design-merge` branch!
Create a feature branch and use `git status` to list changed files.
and you'll load every file because no directories are excluded.

(Make sure that the feature branch is a branch off from `source-design-merge` local branch in your machine and not from any other previously worked branch).
```sh
git checkout -b your_feature_branch
git status
```
Add, commit, and push the files that you'd like to add to your pr:
```sh
git add file-a
git add file-b
git commit -m 'message about your changes'
git push origin your_feature_branch
```
Visit the [documentation repo](https://github.com/plotly/documentation) and open a pull request against the `source-design-merge` branch.
## Continuous Integration

After your PR has been reviewed and approved, you can merge it into the `source-design-merge` branch! Your changes haven't been deployed yet so they won't be online. That said, be sure to check them after they have been deployed.
Whenever a pull request is made, a continuous integration workflow is initiated. This includes of:
- running the `check-or-enforce-order.py` and `front-matter-ci.py` scripts inside of a Docker container to validate YAML front-matter
- Percy screenshot testing

## Search
Making sure that a pull request passes every continuous integration test is a part of the code review process.

We now have search via algolia implemented on our index and reference documentation pages! Please refer to our [make README](https://github.com/plotly/documentation/blob/source-design-merge/make_instructions.txt) for more information on how search works and instructions on how to update or edit Plotly search indices.
**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/documentation/blob/source-design-merge/.circleci/config.yml.**

## Style Edits
## Other Documentation

Please refer to our [Styles README](https://github.com/plotly/documentation/blob/source-design-merge/style_README.md)
This repository also contains:
- Plotly's Node.js, Matlab, Scala, Julia, and Python V3 graphing libraries documentation
- the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries.
Loading