Skip to content

Commit

Permalink
Merge branch 'master' of https://github.com/WordPress/gutenberg into …
Browse files Browse the repository at this point in the history 
…rnmobile/372-add-title-to-gutenberg-mobile

* 'master' of https://github.com/WordPress/gutenberg: (56 commits)
  Save package-lock.json file changes (#13481)
  Plugin: Deprecate gutenberg_add_responsive_body_class (#13461)
  Add speak messages to the feature toggle component. (#13385)
  Plugin: Deprecate gutenberg_kses_allowedtags (#13460)
  Plugin: Deprecate gutenberg_bulk_post_updated_messages (#13472)
  Plugin: Avoid calling deprecated gutenberg_silence_rest_errors (#13446)
  Plugin: Deprecate gutenberg_remove_wpcom_markdown_support (#13473)
  Fix: Categories block: add custom classes only to wrapper (#13439)
  is-shallow-equal: Use ES5 ruleset from eslint-plugin module (#13428)
  Update and Organize Contributors Guide per #12916 (#13352)
  Dismissible-notices: fix text overlapping icon (X) (#13371)
  Framework: Remove 5.0-merged REST API integrations (#13408)
  Plugin: Remove 5.0-merged block registration functions, integrations (#13412)
  Framework: Bump minimum required WP to 5.x (#13370)
  [Mobile] Improve keyboard hide button (#13415)
  Improve castError handling of non strings (#13315)
  Fix: File block add custom class (#13432)
  Consider making Fullscreen Mode effects visible only on larger screens (#13425)
  Update plugin version to 4.9.0 (#13436)
  DateTimePicker: fix prop warning for (#12933)
  ...
  • Loading branch information
@daniloercoli
daniloercoli committed Jan 24, 2019
2 parents b94bede + 996dab8 commit b5e679b
Show file tree
Hide file tree
Showing 170 changed files with 6,598 additions and 9,964 deletions.
146 changes: 14 additions & 132 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@

Thank you for thinking about contributing to WordPress' Gutenberg project! If you're unsure of anything, know that you're 💯 welcome to submit an issue or pull request on any topic. The worst that can happen is that you'll be politely directed to the best location to ask your question or to change something in your pull request. We appreciate any sort of contribution and don't want a wall of rules to get in the way of that.

As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](/CODE_OF_CONDUCT.md).

Before contributing, we encourage you to read our [Contributing Policy](CONTRIBUTING.md) (you're here already!) and our [Handbook](https://wordpress.org/gutenberg/handbook/). If you have any questions on any of these, please open an issue so we can help clarify them.
Before contributing, we encourage you to review the [Contributor Handbook](https://wordpress.org/gutenberg/handbook/contributors/). If you have any questions, please ask, either in Slack or open an issue in GitHub so we can help clarify.

All WordPress projects are [licensed under the GPLv2+](LICENSE.md), and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.
All WordPress projects are [licensed under the GPLv2+](/LICENSE.md), and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.

This document covers the technical details around setup, and submitting your contribution to the Gutenberg project.

## Getting Started

Expand Down Expand Up @@ -60,7 +62,7 @@ Welcome to...
```

The WordPress installation should be available at `http://localhost:8888` (**Username**: `admin`, **Password**: `password`).
Inside the "docker" directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your `docker-compose.override.yml` file. If you're running [e2e tests](https://wordpress.org/gutenberg/handbook/reference/testing-overview/#end-to-end-testing), this change will be used correctly.
Inside the "docker" directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your `docker-compose.override.yml` file. If you're running [e2e tests](/docs/contributors/testing-overview.md#end-to-end-testing), this change will be used correctly.

To bring down this local WordPress instance later run:
```
Expand Down Expand Up @@ -104,155 +106,35 @@ For example, `add/gallery-block` means you're working on adding a new gallery bl

You can pick among all the <a href="https://github.com/WordPress/gutenberg/issues">tickets</a>, or some of the ones labelled <a href="https://github.com/WordPress/gutenberg/labels/Good%20First%20Issue">Good First Issue</a>.

The workflow is documented in greater detail in the [repository management](./docs/contributors/repository-management.md) document.
The workflow is documented in greater detail in the [repository management](/docs/contributors/repository-management.md) document.

## Testing

Gutenberg contains both PHP and JavaScript code and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](./docs/contributors/testing-overview.md).
Gutenberg contains both PHP and JavaScript code and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](/docs/contributors/testing-overview.md).

## Managing Packages

This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm].

### Creating a New Package

When creating a new package, you need to provide at least the following:

1. `package.json` based on the template:
```json
{
"name": "@wordpress/package-name",
"version": "1.0.0-beta.0",
"description": "Package description.",
"author": "The WordPress Contributors",
"license": "GPL-2.0-or-later",
"keywords": [
"wordpress"
],
"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/package-name/README.md",
"repository": {
"type": "git",
"url": "https://github.com/WordPress/gutenberg.git"
},
"bugs": {
"url": "https://github.com/WordPress/gutenberg/issues"
},
"main": "build/index.js",
"module": "build-module/index.js",
"react-native": "src/index",
"dependencies": {
"@babel/runtime": "^7.0.0"
},
"publishConfig": {
"access": "public"
}
}
```
This assumes that your code is located in the `src` folder and will be transpiled with `Babel`.
2. `.npmrc` file which disables creating `package-lock.json` file for the package:
```
package-lock=false
```
3. `README.md` file containing at least:
- Package name
- Package description
- Installation details
- Usage example
- `Code is Poetry` logo (`<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>`)

### Maintaining Changelogs

Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. All packages should follow the [Semantic Versioning (`semver`) specification](https://semver.org/).

The developer who proposes a change (pull request) is responsible for choosing the correct version increment (`major`, `minor`, or `patch`) according to the following guidelines:

- Major version X (X.y.z | X > 0) should be changed with any backward incompatible/"breaking" change. This will usually occur at the final stage of deprecating and removing of a feature.
- Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backward compatible manner. It must be incremented if any public API functionality is marked as deprecated.
- Patch version Z (x.y.Z | x > 0) should be incremented when you make backward compatible bug fixes.

When in doubt, refer to [Semantic Versioning specification](https://semver.org/).

_Example:_

```md
## v1.2.2 (Unreleased)

### Bug Fix

- ...
- ...
```

- If you need to add something considered a bug fix, you add the item to `Bug Fix` section and leave the version as 1.2.2.
- If it's a new feature, you add the item to `New Feature` section and change version to 1.3.0.
- If it's a breaking change you want to introduce, add the item to `Breaking Change` section and bump the version to 2.0.0.
- If you struggle to classify a change as one of the above, then it might be not necessary to include it.

The version bump is only necessary if one of the following applies:
- There are no other unreleased changes.
- The type of change you're introducing is incompatible (more severe) than the other unreleased changes.

### Releasing Packages

Lerna automatically releases all outdated packages. To check which packages are outdated and will be released, type `npm run publish:check`.

If you have the ability to publish packages, you _must_ have [2FA enabled](https://docs.npmjs.com/getting-started/using-two-factor-authentication) on your [npm account][npm].

#### Before Releasing

Confirm that you're logged in to [npm], by running `npm whoami`. If you're not logged in, run `npm adduser` to login.

If you're publishing a new package, ensure that its `package.json` file contains the correct `publishConfig` settings:

```json
{
"publishConfig": {
"access": "public"
}
}
```

You can check your package configs by running `npm run lint-pkg-json`.

#### Development Release

Run the following command to release a dev version of the outdated packages, replacing `123456` with your 2FA code. Make sure you're using a freshly generated 2FA code, rather than one that's about to timeout. This is a little cumbersome but helps to prevent the release process from dying mid-deploy.

```bash
NPM_CONFIG_OTP=123456 npm run publish:dev
```

Lerna will ask you which version number you want to choose for each package. For a `dev` release, you'll more likely want to choose the "prerelease" option. Repeat the same for all the outdated packages and confirm your version updates.

Lerna will then publish to [npm], commit the `package.json` changes and create the git tags.

#### Production Release

To release a production version for the outdated packages, run the following command, replacing `123456` with your (freshly generated, as above) 2FA code:

```bash
NPM_CONFIG_OTP=123456 npm run publish:prod
```
This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. This enforces certain steps in the workflow which are described in details in [packages](/packages/README.md) documentation.

Choose the correct version based on `CHANGELOG.md` files, confirm your choices and let Lerna do its magic.
Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](/packages/README.md#maintaining-changelogs) section.

## How Can Designers Contribute?

If you'd like to contribute to the design or front-end, feel free to contribute to tickets labelled [Needs Design](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Design%22) or [Needs Design Feedback](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A"Needs+Design+Feedback%22). We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use <a href="https://www.sketchapp.com/">Sketch</a>, you can grab <a href="https://cloudup.com/cMPXM8Va2cy">the source file for the mockups</a> (updated April 6th).

## Contribute to the Documentation

Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.

To add a new documentation page, you'll have to create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [root-manifest.json](https://github.com/WordPress/gutenberg/blob/master/docs/root-manifest.json).
Documentation is automatically synced from `master` to the [Gutenberg Handbook](https://wordpress.org/gutenberg/handbook/) every 15 minutes.

### `@wordpress/component`

If you're contributing to the documentation of any component from the `@wordpress/component` package, take a look at its [guidelines for contributing](./packages/components/CONTRIBUTING.md).
If you're contributing to the documentation of any component from the `@wordpress/component` package, take a look at its [guidelines for contributing](/packages/components/CONTRIBUTING.md).

## Reporting Security Issues

Please see [SECURITY.md](./SECURITY.md).
Please see [SECURITY.md](/SECURITY.md).

## Localizing Gutenberg Plugin

Expand Down
2 changes: 1 addition & 1 deletion bin/generate-public-grammar.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ function flatten( expression ) {

fs.writeFileSync(
path.join( __dirname, '..', 'docs', 'grammar.md' ), `
# The Gutenberg block grammar
# Block Grammar
${ flatten( grammar ) }
` );
80 changes: 17 additions & 63 deletions docs/contributors/coding-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,76 +102,30 @@ If an API must be exposed but is clearly not intended to be supported into the f
export { __unstableDoAction } from './api';
```

### Variable Naming
### Objects

Gutenberg inherits [WordPress' naming conventions of camel-casing](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/#naming-conventions):

>Variable and function names should be full words, using camel case with a lowercase first letter. This is an area where this standard differs from the WordPress PHP coding standards.
>
>Constructors intended for use with `new` should have a capital first letter (UpperCamelCase).
However, Gutenberg is more specific about its handling of abbreviations, acronyms, constants, and the ES2015 class construct.

#### Abbreviations and Acronyms

[*Abbreviations*](https://en.wikipedia.org/wiki/Abbreviation) must be written as camel case, with an initial capitalized letter followed by lowercase letters.

[*Acronyms*](https://en.wikipedia.org/wiki/Acronym) must be written with each of its composing letters capitalized. This is intended to reflect that each letter of the acronym is a proper word in its expanded form.

If an abbreviation or an acronym occurs at the start of a variable name, it must be written to respect the camelcase naming rules covering the first letter of a variable or class definition. For variable assignment, this means writing the abbreviation entirely as lowercase. For class definitions, its initial letter should be capitalized.

**Examples:**

```js
// "Id" is an abbreviation of "Identifier":
const userId = 1;

// "DOM" is an acronym of "Document Object Model":
const currentDOMDocument = window.document;

// Acronyms and abbreviations at the start of a variable name are consistent
// with camelcase rules covering the first letter of a variable or class.
const domDocument = window.document;
class DOMDocument {}
class IdCollection {}
```

#### Class Definition

A [`class` definition](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) must use the UpperCamelCase convention, regardless of whether it is intended to be used with `new` construction.

**Example:**
When possible, use [shorthand notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#New_notations_in_ECMAScript_2015) when defining object property values:

```js
class Earth {
static addHuman( human ) {
Earth.humans.push( human );
}

static getHumans() {
return Earth.humans;
}
}

Earth.humans = [];
```

All `@wordpress/element` Components, including stateless function components, should be named using Class Definition naming rules, both for consistency and to reflect the fact that a component may need to be transitioned from a function to a class without breaking compatibility.

**Examples:**
const a = 10;

```js
class MyComponent extends Component {}
// Bad:
const object = {
a: a,
performAction: function() {
// ...
},
};

function MyComponent() {}
// Good:
const object = {
a,
performAction() {
// ...
},
};
```

#### Constants

An exception to camel case is made for constant values which are never intended to be reassigned or mutated. Such variables must use the [SCREAMING_SNAKE_CASE convention](https://en.wikipedia.org/wiki/Snake_case).

In almost all cases, a constant should be defined in the top-most scope of a file. It is important to note that [JavaScript's `const` assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) is conceptually more limited than what is implied here, where a value assigned by `const` in JavaScript can in-fact be mutated, and is only protected against reassignment. A constant as defined in these coding guidelines applies only to values which are expected to never change, and is a strategy for developers to communicate intent more so than it is a technical restriction.

### Strings

String literals should be declared with single-quotes *unless* the string itself contains a single-quote that would need to be escaped–in that case: use a double-quote. If the string contains a single-quote *and* a double-quote, you can use ES6 template strings to avoid escaping the quotes.
Expand Down
Loading

0 comments on commit b5e679b

Please sign in to comment.