Commit c938264c authored by jrockowitz's avatar jrockowitz

Issue #2830992 by jrockowitz: Create the Webform-8.x-5.x branch and grant...

Issue #2830992 by jrockowitz: Create the Webform-8.x-5.x branch and grant @jrockowitz maintainer access
parent 17a85661

Too many changes to show.

To preserve performance only 356 of 356+ files are displayed.

# The mkdocs output directory and GitHub pages directory.
site
gh-pages
*.patch
interdiff-*.txt
Development Cheatsheet
----------------------
Below are useful commands and cheatsheets that make it a little easier for
me to maintain the Webform module.
### Patching
**[Create and manage patches](https://www.drupal.org/node/707484)**
```bash
# Create and checkout issue branch
git checkout -b [issue-number]-[issue-description]
# Push issue branch to D.O. (optional)
git push -u origin [issue-number]-[issue-description]
# Create patch by comparing (current) issue branch with 8.x-1.x branch
git diff 8.x-1.x > [project_name]-[issue-description]-[issue-number]-[comment-number]-[drupal-version].patch
```
**Ignoring *.patch, *.diff, and .gitignore files**
```bash
cat >> .gitignore <<'EOF'
.gitignore
*.patch
*.diff
EOF
```
**[Apply patch](https://www.drupal.org/node/1399218)**
```bash
curl https://www.drupal.org/files/[patch-name].patch | git apply -
```
**[Revert patch](https://www.drupal.org/patch/reverse)**
```bash
curl https://www.drupal.org/files/[patch-name].patch | git apply -R -
```
### Branching
**Merge branch**
```bash
# Merge branch with all commits
git checkout 8.x-1.x
git merge [issue-number]-[issue-description]
git push
# Merge branch as a single new commit
git checkout 8.x-1.x
git merge --squash [issue-number]-[issue-description]
git commit -m 'Issue #[issue-number]: [issue-description]'
git push
```
**Exporting a branch**
```bash
# Create a zip archive for a branch
git archive --format zip --output webform-[issue-number]-[issue-description].zip [issue-number]-[issue-description]
```
**Delete issue branch**
```bash
# Delete local issue branch.
git branch -d [issue-number]-[issue-description]
# Delete remote issue branch.
git push origin :[issue-number]-[issue-description]
```
### [Interdiff](https://www.drupal.org/documentation/git/interdiff)
```bash
interdiff \
[issue-number]-[old-comment-number].patch \
[issue-number]-[new-comment-number].patch \
> interdiff-[issue-number]-[old-comment-number]-[new-comment-number].txt
```
### GitFlow
Below is a cheatsheet for using [GitFlow](https://www.drupal.org/node/2406727)
for development.
```bash
# Create branch
git checkout 8.x-1.x
git checkout -b [issue-number]-[issue-description]
git push -u origin [issue-number]-[issue-description]
# Create patch
git diff 8.x-1.x > [project_name]-[issue-description]-[issue-number]-00.patch
# Merge branch with all commits
git checkout 8.x-1.x
git merge [issue-number]-[issue-description]
git push
# Merge branch as a single new commit
git checkout 8.x-1.x
git merge --squash [issue-number]-[issue-description]
git commit -m 'Issue #[issue-number]: [issue-description]'
git push
# Delete branch
git branch -D [issue-number]-[issue-description]
git push origin :[issue-number]-[issue-description]
```
### Drush
**Reinstall Webform module.**
```bash
drush php-eval 'module_load_include('install', 'webform'); webform_uninstall();'; drush cron;
drush php-eval 'module_load_include('install', 'webform_node'); webform_node_uninstall();'; drush cron;
drush webform-purge --all -y; drush pmu -y webform_test; drush pmu -y webform_devel; drush pmu -y webform_examples; drush pmu -y webform_templates; drush pmu -y webform_ui; drush pmu -y webform_node; drush pmu -y webform;
drush en -y webform webform_ui webform_devel webform_examples webform_templates webform_node;
# Optional.
drush en -y webform_test;
drush en -y webform_test_third_party_settings;
drush en -y webform_translation_test;
drush pmu -y webform_test_third_party_settings webform_translation_test;
```
**Reinstall Webform Test module.**
```bash
drush webform-purge --all -y; drush pmu -y webform_test; drush en -y webform_test;
```
**Manage Webform module configuration using the [Features](https://www.drupal.org/project/features) module**
```
# Make sure all modules that are going to be exported are enabled
drush en -y webform webform_examples webform_templates webform_test webform_node;
# Show the difference between the active config and the default config.
drush features-diff webform
drush features-diff webform_test
# Export webform configuration from your site.
drush features-export -y webform
drush features-export -y webform_test
drush features-export -y webform_examples
drush features-export -y webform_templates
drush features-export -y webform_node
# Tidy webform configuration from your site.
drush webform-tidy -y --dependencies webform
drush webform-tidy -y --dependencies webform_test
drush webform-tidy -y --dependencies webform_examples
drush webform-tidy -y --dependencies webform_templates
drush webform-tidy -y --dependencies webform_node
# Re-import all webform configuration into your site.
drush features-import -y webform
drush features-import -y webform_test
drush features-import -y webform_examples
drush features-import -y webform_templates
drush features-import -y webform_node
```
**Install extra modules.**
```bash
drush en -y webform captcha image_captcha honeypot validators;
```
**Create test roles and users.**
```bash
drush role-create developer
drush role-add-perm developer 'view the administration theme,access toolbar,access administration pages,access content overview,access webform overview,administer webform,edit webform assets,administer blocks,administer nodes'
drush user-create developer --password="developer"
drush user-add-role developer developer
drush role-create admin
drush role-add-perm admin 'view the administration theme,access toolbar,access administration pages,access content overview,access webform overview,administer webform submission'
drush user-create admin --password="admin"
drush user-add-role admin admin
drush role-create manager
drush role-add-perm manager 'view the administration theme,access toolbar,access administration pages,access content overview,access webform overview'
drush user-create manager --password="manager"
drush user-add-role manager manager
drush role-create viewer
drush role-add-perm viewer 'view the administration theme,access toolbar,access administration pages,access content overview,access webform overview,view any webform submission'
drush user-create viewer --password="viewer"
drush user-add-role viewer viewer
drush role-create user
drush user-create user --password="user"
drush user-add-role user user
drush role-create any
drush user-create any --password="any"
drush role-add-perm any 'view the administration theme,access administration pages,access toolbar,access webform overview,edit webform assets,create webform,edit any webform,delete any webform,view webform submissions any node,edit webform submissions any node,delete webform submissions any node'
drush user-add-role any any
drush role-create own
drush user-create own --password="own"
drush role-add-perm own 'view the administration theme,access administration pages,access toolbar,access webform overview,edit webform assets,create webform,edit own webform,delete own webform,view webform submissions own node,edit webform submissions own node,delete webform submissions own node'
drush user-add-role own own
```
**Create test submissions for 'Contact' and 'Example: Elements' webform.**
```bash
drush webform-generate contact
drush webform-generate example_elements
```
**Test update hooks**
```bash
drush php-eval 'module_load_include('install', 'webform'); ($message = webform_update_8001()) ? drupal_set_message($message) : NULL;'
```
**Access developer information**
```bash
drush role-add-perm anonymous 'access devel information'
drush role-add-perm authenticated 'access devel information'
```
**Reinstall**
```bash
drush -y site-install\
--account-mail="example@example.com"\
--account-name="webmaster"\
--account-pass="drupal.admin"\
--site-mail="example@example.com"\
--site-name="Drupal 8 (dev)";
# Enable core modules
drush -y pm-enable\
book\
simpletest\
telephone\
language\
locale\
content_translation\
config_translation;
# Disable core modules
drush -y pm-uninstall\
update;
# Enable contrib modules
drush -y pm-enable\
devel\
devel_generate\
kint\
webprofiler\
webform\
webform_devel\
webform_examples\
webform_node\
webform_templates\
webform_test\
webform_translation_test;
```
Steps for creating a new release
--------------------------------
1. Cleanup code
2. Export configuration
3. Review code
4. Run tests
5. Generate release notes
6. Tag and create a new release
7. Update project page
8. Update documentation
1. Cleanup code
---------------
[Convert to short array syntax](https://www.drupal.org/project/short_array_syntax)
drush short-array-syntax webform
Tidy YAML files
drush webform-tidy webform;
drush webform-tidy webform_ui;
drush webform-tidy webform_test;
drush webform-tidy webform_translation_test;
2. Export configuration
-----------------------
# Install all sub-modules.
drush en -y webform webform_test webform_translation_test webform_examples webform_templates webform_node
# Export webform configuration from your site.
drush features-export -y webform
drush features-export -y webform_test
drush features-export -y webform_translation_test
drush features-export -y webform_examples
drush features-export -y webform_templates
# Tidy webform configuration from your site.
drush webform-tidy -y --dependencies webform
drush webform-tidy -y --dependencies webform_test
drush features-tidy -y --dependencies webform_translation_test
drush webform-tidy -y --dependencies webform_examples
drush webform-tidy -y --dependencies webform_templates
# Reset certain files.
cd modules/sandbox/webform
git reset HEAD webform.info.yml
git reset HEAD tests/modules/webform_test/webform_test.info.yml
git reset HEAD tests/modules/webform_test/config/optional
3. Review code
--------------
[Online](http://pareview.sh)
http://git.drupal.org/project/webform.git 8.x-1.x
[Commandline](https://www.drupal.org/node/1587138)
# Make sure to remove the node_modules directory.
rm -Rf node_modules
# Check Drupal coding standards
phpcs --standard=Drupal --extensions=php,module,inc,install,test,profile,theme,css,info modules/sandbox/webform
# Check Drupal best practices
phpcs --standard=DrupalPractice --extensions=php,module,inc,install,test,profile,theme,js,css,info modules/sandbox/webform
[File Permissions](https://www.drupal.org/comment/reply/2690335#comment-form)
# Files should be 644 or -rw-r--r--
find * -type d -print0 | xargs -0 chmod 0755
# Directories should be 755 or drwxr-xr-x
find . -type f -print0 | xargs -0 chmod 0644
4. Run tests
------------
[SimpleTest](https://www.drupal.org/node/645286)
# Run all tests
php core/scripts/run-tests.sh --url http://localhost/d8_dev --module webform
[PHPUnit](https://www.drupal.org/node/2116263)
# Execute all PHPUnit tests.
cd core
php ../vendor/phpunit/phpunit/phpunit --group WebformUnit
# Execute individual PHPUnit tests.
cd core
export SIMPLETEST_DB=mysql://drupal_d8_dev:drupal.@dm1n@localhost/drupal_d8_dev;
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/tests/src/Unit/WebformTidyTest.php
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/tests/src/Unit/WebformHelperTest.php
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/tests/src/Unit/WebformElementHelperTest.php
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/tests/src/Unit/WebformOptionsHelperTest.php
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/tests/src/Unit/WebformArrayHelperTest.php
php ../vendor/phpunit/phpunit/phpunit ../modules/sandbox/webform/src/Tests/WebformEntityElementsValidationUnitTest.php
5. Generate release notes
-------------------------
[Git Release Notes for Drush](https://www.drupal.org/project/grn)
drush release-notes --nouser 8.x-1.0-VERSION 8.x-1.x
6. Tag and create a new release
-------------------------------
[Tag a release](https://www.drupal.org/node/1066342)
git tag 8.x-1.0-VERSION
git push --tags
git push origin tag 8.x-1.0-VERSION
[Create new release](https://www.drupal.org/node/add/project-release/2640714)
7. Update project page
----------------------
[Export README](https://www.drupal.org/project/readme)
# Update project page
drush readme-export --project --path='docs/index.md' webform
open https://www.drupal.org/node/2640714/edit
[Edit project page](https://www.drupal.org/node/2640714/edit)
8. Update documentation
-----------------------
[Update Roadmap](http://webform.io/developers/roadmap/)
npm install; grunt docs-deploy;
Webform
---------
> GOOD NEWS!!!
### The Webform module is moving to the Webform module.
An experimental Webform to Webform migration module is now being included
with the Webform module. Read more about the
[Webform to Webform migration](https://www.drupal.org/node/2827845)
### About this Module
The Webform module is a webform builder and submission manager for Drupal 8.
The primary use case for this module is to:
- **Build** a new webform or duplicate an existing template
- **Publish** the webform as a page, node, or block
- **Collect** submissions
- **Send** confirmations and notifications
- **Review** submissions online
- **Download** submissions as a CSV
### Goals
- A comprehensive webform and survey building solution for Drupal 8.
- A stable, maintainable, and tested API for building webforms and handling submission.
- A pluggable/extensible API for custom webform elements and submission handling.
### Demo
> Evaluate this project online using [simplytest.me](https://simplytest.me/project/drupal/8.2.x?add[]=webform).
> [Watch a demo](http://youtu.be/9jSOOEpzAy8) of the Webform module.
### Blog Posts & Articles
- [Getting NYU onto Webform](https://www.fourkitchens.com/blog/article/getting-nyu-yaml-form)
- [Webforms for Drupal 8](https://www.gaiaresources.com.au/yaml-forms-drupal-8/)
### Installing the Webform Module
1. Copy/upload the webform module to the modules directory of your Drupal
installation.
2. Enable the 'Webform' module and desired sub-modules in 'Extend'.
(/admin/modules)
3. Set up user permissions. (/admin/people/permissions#module-webform)
4. Build a new webform (/admin/structure/webform)
or duplicate an existing template (/admin/structure/webform/templates).
5. Publish your webform as a:
- **Page:** By linking to the published webform.
(/webform/contact)
- **Node:** By creating a new node that references the webform.
(/node/add/webform)
- **Block:** By placing a Webform block on your site.
(/admin/structure/block)
6. (optional) Install third party libraries(/admin/help/webform).
7. (optional) Install add-on contrib modules](/admin/structure/webform/addons).
### Releases
Even though the Webform module is still under active development with
regular [beta releases](https://www.drupal.org/documentation/version-info/alpha-beta-rc),
all existing configuration and submission data will be maintained and updated
between releases. **APIs can and will be changing** while this module moves
from beta releases to a final release candidate.
Simply put, if you install and use the Webform module out of the box AS-IS,
you _should_ be okay. Once you start extending webforms with plugins, altering
hooks, and overriding templates, you will need to read each release's
notes and assume that _things will be changing_.
### Similar Modules
- **[Comparison of Webform Building Modules](https://www.drupal.org/node/2083353)**
Drupal has a lot of modules aimed at helping site builders and users add webforms
to their sites. The [Comparison of Webform Building Modules](https://www.drupal.org/node/2083353)
page includes rough comparisons of three of them for Drupal 8 and five of them
for Drupal 7.
---
- **[Contact](https://www.drupal.org/documentation/modules/contact) +
[Contact Storage](https://www.drupal.org/project/contact_storage)**
The Contact module allows site visitors to send emails to other authenticated
users and to the site administrator. The Contact Storage module provides
storage for Contact messages which are fully-fledged entities in Drupal 8.
Many of its features are likely to be moved into Drupal Core.
- **[Eform](https://www.drupal.org/project/eform)**
The EForm module enables you to create front-end webforms (fieldable entities),
which contain fields that you define! These webforms use the standard Drupal
fields.
[Is this module still needed?](https://www.drupal.org/node/2809179)
Description
-----------
This module adds a webform content type to your Drupal site.
A webform can be a questionnaire, contact or request form. These can be used
by visitor to make contact or to enable a more complex survey than polls
provide. Submissions from a webform are saved in a database table and
can optionally be mailed to e-mail addresses upon submission.
Requirements
------------
Drupal 7.x
See https://www.drupal.org/project/webform for additional requirements.
Installation
------------
1. Copy the entire webform directory the Drupal sites/all/modules directory.
2. Login as an administrator. Enable the module in the "Administer" -> "Modules"
3. (Optional) Edit the settings under "Administer" -> "Configuration" ->
"Content authoring" -> "Webform settings"
4. Create a webform node at node/add/webform.
Upgrading from previous versions
--------------------------------
Note that you must be running the latest 3.x version of Webform (for either
Drupal 6 or Drupal 7) before upgrading to Webform 4.x.
If you have contributed modules, custom modules, or theming on your Webforms,
please read over the documentation for upgrading your code for Webform 4.x at
https://drupal.org/node/1609324.
1. MAKE A DATABASE BACKUP. Upgrading to Webform 4.x makes a signficant number of
database changes. If you encounter an error and need to downgrade, you must
restore the previous database. You can make a database backup with your
hosting provider, using the Backup and Migrate module, or from the command
line.
2. Copy the entire webform directory the Drupal modules directory, replacing the
old copy of Webform. DO NOT KEEP THE OLD COPY in the same directory or
anywhere Drupal could possibily find it. Delete it from the server.
3. Login as an administrative user or change the $update_free_access in
update.php to TRUE.
4. Run update.php (at http://www.example.com/update.php).
Support
-------
Please use the issue queue for filing bugs with this module at