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

Fixes to the README; creation of echidna manifest #10

Merged
merged 7 commits into from
Aug 20, 2021
Merged

Fixes to the README; creation of echidna manifest #10

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
277664d
Adding echidna configuration file (set to FPWD)
aphillips Aug 9, 2021
f9bd0de
Merge pull request #1 from w3c/gh-pages
aphillips Aug 10, 2021
03cace1
Address xfq@ and r12a@'s comments.
aphillips Aug 10, 2021
26041a2
Merge remote-tracking branch 'refs/remotes/origin/gh-pages' into gh-p…
aphillips Aug 10, 2021
64f83aa
Preparing FPWD.
aphillips Aug 18, 2021
264cc2b
Restoring WD status, updated (commented out) previous publication date
aphillips Aug 20, 2021
d820ba7
Experimenting with changes per r12a to eliminate the phantom div
aphillips Aug 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 5 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,14 @@ To follow the work, you can 'Watch' this repository using the control above, or

### Contributing

All contributors should read and agree with [CONTRIBUTING.md](https://github.com/w3c/localizable-manifests/blob/gh-pages/CONTRIBUTING.md).
All contributors should read and agree with [CODE_OF_CONDUCT.md](https://github.com/w3c/localizable-manifests/blob/gh-pages/CODE_OF_CONDUCT.md).

Editors should be familiar with and use the following:

- [Github guidelines for working with i18n documents](https://w3c.github.io/i18n-activity/guidelines/github)
- [Editorial guidelines for working with i18n documents](https://w3c.github.io/i18n-activity/guidelines/editing)
- [Github guidelines for working with i18n documents](https://www.w3.org/International/i18n-activity/guidelines/github)
- [Editorial guidelines for working with i18n documents](https://www.w3.org/International/i18n-activity/guidelines/editing)

### Links
- [Working Group Home Page](https://w3c.github.io/i18n-activity/i18n-wg/)

- [Working Group Home Page](https://www.w3.org/International/i18n-activity/i18n-wg/)

3 changes: 3 additions & 0 deletions echidna
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# ECHIDNA configuration
Copy link
Member

Choose a reason for hiding this comment

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

Note, we don't need this file anymore. The new publishing system takes care of it for us so feel free to delete this.

When we are ready to auto publish, I can help set that up. Just give me a ping.

Copy link
Contributor

Choose a reason for hiding this comment

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

Marcos, do you have a pointer to some documentation around this?

Are you referring to the auto-publish feature, that republishes your document every time you change the ED? We weren't planning to use that, since we often want to get people to review text before replacing the NOTE/WD in TR.

Copy link
Member

Choose a reason for hiding this comment

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

Marcos, do you have a pointer to some documentation around this?

https://w3c.github.io/spec-prod/

Are you referring to the auto-publish feature, that republishes your document every time you change the ED?

Yes.

We weren't planning to use that, since we often want to get people to review text before replacing the NOTE/WD in TR.

Sorry, I'm bit confused... ".pr_preview" and pull requests are used for reviews, no? The W3C would like to move away from using Github pages in the manner you suggest above (otherwise the stuff on TR is always unnecessarily stale).

Copy link
Contributor

Choose a reason for hiding this comment

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

@marcoscaceres it's not the way we've been working. A couple of reasons:

  1. we commonly need more than one PR/commit to get a change right and complete, and we don't usually want to expose (sometimes incorrect) workings to a Note. We tend to move things to Note, rather than WD, when we feel that there is a certain amount of stability and the text is reliable. When we update a Note, we usually announce the update on Twitter and in our news feed.
  2. we have almost 30 documents that need to be updated regularly but the changes involve no PRs or changes to the main html file at all. These are the gap-analysis documents. So there's nothing to trigger an auto-update for those.
  3. the pr_preview previews are often not good enough to check the proposed changes to the document. For example, some styling and javascript get omitted. It's also sometimes easier, especially for complex edits, to generate a new ED so that people can point to it, and/or add further edits that would otherwise produce conflicts. It's useful in those cases not to automatically push the changes to /TR, especially if we're working on something we elevated to Note status.

What i think would be helpful in order to keep TR from getting unnecessarily stale, is a dashboard or (better) notification service which tells me, for each of our 30-40 drafts being worked on, what the gap is between last publication to TR and most recent changes to the ED. If we were pinged once a week with an email that listed items over a week old, with categories such as 'Published this month', 'Published 1-3 months ago', 'Published over 6 months ago', etc. that would be quite useful as a reminder to consider updating TR. That said, we do try to keep on top of things.

Copy link
Member

Choose a reason for hiding this comment

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

I agree that /TR being stale is a problem. Even the editor themselves sometimes thinks that the /TR version is the latest draft and writes a long issue about some section, but it turns out that the content in the ED is already different.

I think the first two problems raised by @r12a can be solved by manually publishing. It is tracked in w3c/spec-prod#6 (The first problem can be solved by better review of changes to the documents, but is difficult to avoid completely.)

The third problem is indeed an important problem, which is also one of the reasons why the CSSWG puts new features in specs with a higher level. Long-standing PRs are bad for discoverability and tend to cause merge conflicts. As for the PR Preview issue itself, it is tracked in tobie/pr-preview#87

I agree that the notification service idea is a way to solve this issue. I look at the freshness of specs regularly in other groups, but if there is an automatic reminder, it would be better.

index.html?specStatus=FPWD;shortName=localizable-manifests respec
local.css
10 changes: 5 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<script src="https://www.w3.org/Tools/respec/respec-w3c" async="" class="remove"></script>
<script class="remove">
var respecConfig = {
specStatus: "ED",
specStatus: "WD",
Copy link
Contributor

Choose a reason for hiding this comment

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

The status needs to be restored to ED, not WD.

edDraftURI: "https://w3c.github.io/localizable-manifests",
shortName: "localizable-manifests",
editors: [
Expand All @@ -15,9 +15,9 @@
}
],
// if you wish the publication date to be other than today, set this
//publishDate: "2015-04-23",
//publishDate: "2021-08-24",
//previousMaturity: "WD",
//previousPublishDate: "2015-04-23",
//previousPublishDate: "2021-08-24",
noRecTrack: true,
group: "i18n",
github: "w3c/localizable-manifests",
Expand Down Expand Up @@ -57,7 +57,7 @@ <h2>Introduction</h2>

<p>Some examples of specifications like this include Webapp [[APPMANIFEST]], Miniapp [[MINIAPP-MANIFEST]], and ePub [[EPUB-33]].</p>

<p>Manifest file formats usually contain <a href="https://w3c.github.io/i18n-glossary/#def_syntactic_content">syntactic</a> or <a href="https://w3c.github.io/i18n-glossary/#def_user_supplied_value">user-supplied values</a> that are not localizable. But most manifest file formats also contain at least some <a href="https://w3c.github.io/i18n-glossary/#def_localizable_content">localizable content</a> fields. A specification that defines a manifest file format that includes localizable content values needs to provide a means for users to localize the manifest into different languages. This document covers the pros and cons of common designs, along with some best practices related to building and managing manifests.</p>
<p>Manifest file formats usually contain <a href="https://www.w3.org/TR/i18n-glossary/#def_syntactic_content">syntactic</a> or <a href="https://www.w3.org/TR/i18n-glossary/#def_user_supplied_value">user-supplied values</a> that are not localizable. But most manifest file formats also contain at least some <a href="https://www.w3.org/TR/i18n-glossary/#def_localizable_content">localizable content</a> fields. A specification that defines a manifest file format that includes localizable content values needs to provide a means for users to localize the manifest into different languages. This document covers the pros and cons of common designs, along with some best practices related to building and managing manifests.</p>

<p>These (and many other) best practices, along with links to supporting materials, can also be found in the <cite>Internationalization Best Practices for Spec Developers</cite> [[INTERNATIONAL-SPECS]]. In addition to the best practices found here, additional best practices relating to language metadata on the Web can be found in [[STRING-META]]. Core terminology can also be found in the <cite>Internationalization Glossary</cite> [[I18N-GLOSSARY]].</p>

Expand All @@ -77,7 +77,7 @@ <h2>Requirements and Use Cases</h2>

<p><dfn data-lt="shorthand">Shorthand Description Manifest.</dfn> Other manifests are meant to be used as a shorthand description of the document or application. Manifests like this are often downloaded by the client: retrieving multiple files has latency, size, and storage implications that point toward fewer files or less modular approaches.</p>

<p>Another consideration is the <a href="https://w3c.github.io/i18n-glossary/#dfn-language-negotiation">language negotiation</a> strategy employed by the specification.</p>
<p>Another consideration is the <a href="https://www.w3.org/TR/i18n-glossary/#dfn-language-negotiation">language negotiation</a> strategy employed by the specification.</p>

<p>Bear in mind that modern operating environments support quite extensive sets of available locales and that application owners often wish to satisfy diverse audiences with a single localized application or document. While examples in specifications necessarily are constrained to maybe three or four locales, actual applications with 50 or more specific locales are not uncommon.</p>
</section>
Expand Down