New Upstream is a Composer-based Drupal 8 application hosted on Pantheon. Follow this README to create your local environment, and to learn the best practices for effectively contributing to the project.
See the setup documentation if you are installing VirtualBox, Docksal, or Terminus for the first time. Once you meet the requirements, clone the this repository into your Docksal projects directory and initialize the site:
git clone firstname.lastname@example.org:electriccitizen/newupstream.git
Move to your project's root folder and initialize the site:
Once the site is up, you are ready to start working:
- Local: http://newupstream.docksal
- Dev: http://dev-newupstream.pantheonsite.io
- User: admin/admin (local)
You can run fin init any time you want to reset or guarantee that your local environment is in a safe one-to-one state with your upstream environment.
Here are some other helpful
fin commands that you will likely use in your day-to-day work:
fin start to start your project services (or
fin up if you need to re-load configuration for xdebug etc.)
fin stop to stop your project services (recommended)
See (working with Docksal)[docs/local/DOCKSAL.md] for additional Docksal commands and tips.
See troubleshooting Docksal if things go bad.
Here is a safe workflow that will help prevent lost work and other problems.
fin sync (?) to ensure your local site is synced with the upstream environment before starting a new task
git checkout -b <your-feature-branch> to checkout a new feature branch and do your thing
fin drush cex to export your changes
git add to add any new configuration, theme, or custom module files
git commit to commit your changes and get your feature branch into a safe, recoverable state
fin validate (?) to pull in changes from other team members and check your work against the upstream
git push origin <your-feature-branch> to push your feature branch to Github if everything looks good
If you see errors or merge conflicts after running fin sync or fin validate, you will need to work with the team to understand, fix, and commit the conflicting file(s) or other errors before continuing.
Submit a Github pull request
Each time you push your feature branch, it triggers a Circle CI build to run tests against the development server. You can continue to push to your branch until your work is complete and your site is passing its automated tests. Once your feature branch looks good and is passing its Circle CI tests, submit a Github pull request against your branch. A project maintainer will review the changes and merge into master.
Note: Advanced or otherwise approved users can submit and merge their own PRs, and/or merge and push a feature branch directly into master without a formal pull request. Ask if you have questions, and err on the side of caution.
Be a good citizen
You are working in a team environment and must follow a few rules. If you are careless, it can lead to:
- Losing all of your uncommitted work (bad)
- Overriding or losing the work of others (worse)
- Uninstallable configuration or deploy errors
See this guide to following a safe workflow when using configuration management in Drupal 8. The recommended workflow below follows these best practices, and includes two helper commands (
fin sync and
fin validate) that automate important components of a safe work flow.
These documents contain other important information about the project and working with your local environment.
- Available commands
- Following a safe workflow
- Frontend and theming documentatiob
- Project notes
- Working with Docksal
Support and feedback
If you need support or find any errors or suggested improvements in this README contact email@example.com.
This is an auto-generated document. Keep any custom documents in the