Skip to content
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

Jump to bottom

Serve script documentation #1919

Merged
merged 7 commits into from
Oct 17, 2016
Merged

Serve script documentation #1919

merged 7 commits into from
Oct 17, 2016

Conversation

gemfarmer
Copy link
Contributor

⚠️ WIP

For #1914

@mugizico I forgot that I had started doing this work. Here it is for reference.

@mugizico
Copy link

mugizico commented Oct 3, 2016 •
edited
Loading

running ./serve builds but returns ERROR '/assets/js/search-bundle.js' not found. Per @gemfarmer, this is related to jekyll_pages_search_api gem

@mugizico
Copy link

mugizico commented Oct 4, 2016

I made a few edits on the Contributing.md in the last commit. I am also going to chat with someone from the Writing Lab to see if it can be further improved upon.

@gemfarmer
Copy link
Contributor Author

@mugizico Love the idea of talking with the Writing Lab!

@mugizico
Copy link

mugizico commented Oct 4, 2016

Thanks @gemfarmer! turns out since @coreycaitlin is already part of our team, she will be looking it over for us.

@coreycaitlin coreycaitlin self-assigned this Oct 5, 2016
@coreycaitlin
Copy link

My commit updates the documentation trilogy: README.md, CONTRIBUTING.md, and LICENSE.md. Changes include:

README:

  • Minor updates to clarify the current status of the repo, and move beta and prior-site links to a "History" section
  • Move "Protected branches" information to the CONTRIBUTING file
  • Remove IE version specification because it's redundant with CONTRIBUTING

CONTRIBUTING:

  • Add a table of contents for easier navigation through this very long file
  • Add a "Public contributions" section and move most content into a "18F contributions" section, as those are very different use-cases
  • Clarify "Branches" section to include information about protected branches, as well as documentation of the two processes we'll be using for blog vs. development changes
  • Add mention of where to find us in Slack
  • Move linter information into the "Front end architecture" intro and mention Hound and Circle
  • Minor style edits and some revisions in the "Front end architecture" section, based on conversation with @msecret
  • Add "Standards and benchmarks" header to clarify the scope of the subsections
  • Add link to LICENSE in two places

LICENSE:

In reviewing this, I spotted some inaccuracies, and worked with @brittag to fix them. This file now:

  • Clarifies that not all of the site is in the public domain, because it is based on WDS, which has a mix of licensing situations
  • Links to WDS and notes which parts of the site have non-public-domain assets (for instance, fonts and images)
  • Adds section for contributors

Definitely want review from @gboone and/or @elainekamlley before merging this.

@coreycaitlin
Copy link

Note: These files will need further refinement, but these were big enough changes that I wanted to get them reviewed and discussed before heading too much further down this path.

gboone
gboone suggested changes Oct 13, 2016
View reviewed changes
Copy link
Contributor

@gboone gboone left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, left a few comments to examine before we merge.

CONTRIBUTING.md
### Images
- Will use `<svg>` and `xlink` (looking for link) for icons.
- All blog images should be under 800kb in total, un-minified size.
This is a repo to design a beta version of 18f.gsa.gov using the [U.S. Web Design Standards](https://standards.usa.gov/) and to completely refresh most of the content.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's clarify this to indicate this repo is for 18f.gsa.gov, not a beta version. This is my bad, should have caught that before relaunching the site.

LICENSE.md

Additionally, we waive copyright and related rights in the work
worldwide through the CC0 1.0 Universal public domain dedication.
* Open source work that are not in the public domain
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be?

"Open source works…"

README.md

To dramatically speed up rebuild times (from more than 20 seconds to around 5), you can also run `./serve` or `./build` for step 4. These are shorthand for a combination of commands that disable certain plugins. This is especially useful if you're drafting a blog post or formatting single pages. **With this method you will disable search and all archives.**
To enable the ability to search and see archives, you can run `bundle exec jekyll serve` instead of `./serve` for the server start command. This will **slow down rebuild times dramatically**, so use this command with discretion.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will users still have to clear out an environment variable when they switch from ./serve to the standard bundle exec command?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't answer this one, sadly

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah, meant to tag @gemfarmer and @mugizico on this one.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I switch between using ./serve and bundle exec jekyll serve without clearing out an environment variable. Although, I am not sure if this is related to an earlier issue (before I joined this team)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤔 Maybe this is a non-issue that I invented for myself. Never mind!

@mugizico mugizico changed the base branch from master to dev October 17, 2016 20:40
@coreycaitlin coreycaitlin changed the title [WIP] Serve script documentation Serve script documentation Oct 17, 2016
@mugizico mugizico merged commit 98f3979 into dev Oct 17, 2016
@gboone gboone deleted the new-serve-script branch February 15, 2017 20:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@mugizico mugizico mugizico left review comments

@coreycaitlin coreycaitlin coreycaitlin left review comments

@gboone gboone gboone approved these changes

Assignees

@coreycaitlin coreycaitlin

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@gemfarmer @mugizico @coreycaitlin @gboone