Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Sander Saares
    @sandersaares
    Well, I was unable to get a local install working to try it out (tabatkins/bikeshed#1352) so I request that multiple file support be added to the hosted compiler I can invoke via curl (https://github.com/tabatkins/bikeshed/issues/1353)
    Tab Atkins Jr.
    @tabatkins
    Heya @sandersaares. Thanks for the issue. Yeah, there's no multi-file support in the online version yet.
    How large is the Word file you're currently writing, in pages?
    Sander Saares
    @sandersaares
    234 pages
    Tab Atkins Jr.
    @tabatkins
    Okay, so at least that's probably similar or smaller to the DOM spec, which is about 10k source lines or approximately 400 pages. ^_^
    Sander Saares
    @sandersaares
    I am glad to hear that we are not out of the comfort zone :)
    Sander Saares
    @sandersaares

    Perhaps it would be useful to you to know how we use Bikeshed in our workflow. I will share some details here.

    Our documents consist of contributions from subject matter experts who are as a rule not familiar with Git or writing code. We expect a large set of contributions to come from people just using the text editor in GitHub web GUI, without ever cloning a repo onto their local workstation. In this light, we have made a quick "what is a fork and what is a pull request" style guide for our contributors and editors: https://dashif.org/DocumentAuthoring/

    The contributors and editors generally never interact with Bikeshed or any other tooling. When they create a PR, our build bot publishes the outputs in a comment for author/editor review. We have the Bikeshed HTML and also a PDF generated from this HTML. We also post a link to a diff of this HTML to the master branch HTML (using the W3C HTML diff tool).

    In addition to basic Bikeshed compilation (which we use the web service for), we include diagram generation from PlantUML text files, to enable diagrams to be more easily authored and versioned. Probably there are contributors who will find this uncomfortable and would prefer Visio diagrams etc but I guess it is worth it in the end.

    For contributors who feel more comfortable with using Git and command line tooling, we publish a PowerShell module (both Windows and Linux compatible) called BikeshedDocumentAuthoring that provides them an Invoke-DocumentCompiler command, which when run in a repo matching our workflow performs all the necessary operations to go from source code to final outputs (diagram generation, Bikeshed validate + compile, PDF conversion).

    This workflow was worked out on a smaller 25-page document earlier this year and the experience felt comfortable enough to take it up also for our larger outputs. Will see over the next 6 months how it works out in practice!

    Tab Atkins Jr.
    @tabatkins
    @sandersaares Ooh, ok. That's useful information. In that case, maybe you don't want to be using the web service at all; it would probably be even better to just run Bikeshed on Travis (or your CI of choice)? Check out https://github.com/rtoy/auto-deploy-spec (which is linked from Bikeshed's docs) for thoro details on how to set that up, so you don't have to worry about running it yourself.
    In particular, since that guide sets you up to run Bikeshed on the CI server, it automatically handles everything that a "local" Bikeshed installation would do, including multiple files.
    Sander Saares
    @sandersaares
    Yeah, I considered doing something like that but the sticking point was that I would still like to enable contributors to do the building locally if they wish. Given that I was even unable to make a local install work right on my PC out of the box, I felt like the web service was the only practical way to ensure that contributors can perform a build locally.
    Sander Saares
    @sandersaares

    One of our contributors somehow ended up installing Bikeshed anyway, despite the guide never saying to do so :) He ran into trouble at the Python/pip stage pretty fast.

    I really like Go's style of building self-contained executables. I recall in the past seeing some Python apps also distributed as self-contained directories, "just run unzip and run the binary" style. No idea what packaging like that entails, though - I have not touched Python in 10 years - but a distribution model like that would probably be very helpful in making Bikeshed more foolproof to install.

    Tab Atkins Jr.
    @tabatkins
    Hm, interesting. Did the contributor follow the exact instructions in the docs? I can affirm that the Linux instructions work precisely as advertised, as I've done them several times; other people have contributed and followed the Mac/Windows instructions and successfully installed it.
    Most of the time when people have run into problems installing, it's because they're trying to do something that makes sense to them, rather than just following the actual instructions.
    (The reason I'm trying to find other solutions for you is that the web service isn't maintained by me; it's a completely separate project by @plinss.)
    Sander Saares
    @sandersaares
    I know that he was trying to install it on Windows. However, he did not share with me the details of the issue he was facing (at least he has not responded to my questions so far).
    Sander Saares
    @sandersaares
    How do specref updates get distributed to Bikeshed? An entry was added an hour or two ago. The W3C build service currently does not recognize it. What should my expectations be with regard to specref updates in this aspect?
    Tab Atkins Jr.
    @tabatkins
    The bikeshed-data project runs every 10 minutes, polling all of its data sources for updates. (You can check https://github.com/tabatkins/bikeshed-data/commits/master to see what's been picked up.) I'm unsure of exactly how often the online Bikeshed widget updates its data files.
    (I suspect this commit tabatkins/bikeshed-data@cfd18b3, from 6 hours ago, is the one you're talking about.)
    Sander Saares
    @sandersaares
    Yeah. Looks like it is available now, so whatever the update interval of the online service is, it seems to be less than 24 hours.
    Nicolas Rouquette
    @NicolasRouquette
    I am using bikeshed with our internal github enterprise repository. To enable github issue repository support in bikeshed, I made a small patch to parse https://github.<namespace>/<user-org>/<name> here: tabatkins/bikeshed#1421
    Tab Atkins Jr.
    @tabatkins
    Nice, merged. Didn't even know that was possible!
    Nicolas Rouquette
    @NicolasRouquette

    Although I've had no problems including SVG diagrams created with https://draw.io in bikeshed, I've ran into lots of problems w/ SVG created from https://plantuml.com
    I put some comments about this on a related issue: tabatkins/bikeshed#1403
    Basically, the problem is that with the following:

    <pre class=include>
    path: diagram.svg
    </pre>

    bikeshed is parsing diagram.svg as if it was bikeshed source!
    So, I'm wondering about adding a mechanism to allow including raw HTML in bikeshed, i.e., something like this:

    <pre class=include-html>
    path: diagram.svg
    </pre>

    I realize that this could be abused and a source of difficult to figure out problems. However, its clear that we need some way of letting bikeshed include diagram content without parsing it as bikeshed source.
    Has this topic been discussed/addressed before?

    Nicolas Rouquette
    @NicolasRouquette

    See tabatkins/bikeshed#1427
    This handle things like:

    <dfn lt="examplea">Example A</dfn>
    <dfn lt="exampleb">Example B</dfn>
    <xmp highlight=html>
        <pre class=include-svg>
            path: example.svg
        </pre>
    </xmp>

    where example.svg has hyperlinks like this:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
        <svg viewBox="0 0 150 50" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
            <defs></defs>
            <rect x="10" y="10" width="40" height="40" style="fill: rgb(216, 216, 216);"></rect>
            <a xlink:href="#examplea">
                <text x="20" y="40" style="white-space: pre; fill: rgb(51, 51, 51); font-size: 24px;">A</text>
            </a>
            <rect x="100" y="10" width="40" height="40" style="fill: rgb(216, 216, 216);"></rect>
            <a xlink:href="#exampleb">
                <text x="110" y="40" style="white-space: pre; fill: rgb(51, 51, 51); font-size: 24px;">B</text>
            </a>
            <line style="stroke: rgb(0, 0, 0);" x1="50" y1="30" x2="100" y2="30"></line>
        </svg>

    This is actually taken from a new clause 5.11.2 in the bikeshed spec.

    Nicolas Rouquette
    @NicolasRouquette
    @tabatkins I needed a Bikeshed docker image to run Bikeshed in CI. There was an issue about this: tabatkins/bikeshed#1354 I proposed a PR w/ a Dockerfile and documentation about this here: tabatkins/bikeshed#1428
    Tab Atkins Jr.
    @tabatkins
    @NicolasRouquette Whoops, I missed these messages when I fell behind on email! Sorry about that.
    Nicolas Rouquette
    @NicolasRouquette
    @tabatkins Ok; there is still the PR for 'include-svg' for you to review: tabatkins/bikeshed#1427
    Now that we can build a docker image for bikeshed, are you going to publish an official image somewhere?
    Yuvraj Manral
    @yuvraaaj
    Hello everyone,
    I am Yuvraj, Computer Engineering sophomore. Would like to contribute to bikeshed.
    I've also went through the project proposal for GSoC 2020, which aims to write Python codebase of bikeshed into Rust.
    Would love to proceed with this task.
    Gunwant Jain
    @WantGuns
    Hello!
    I am aspiring for Google Summer of Code 2020. I came across the idea you are mentoring for, i.e. rewriting bikeshed in Rust, and would want to how I can help. I have some adequate experience with RustLang and Python. But still, I request your guidance with relevant resources in order to make better contributions.
    Uday Mewada
    @udaymewada
    Hello everyone,
    Uday Mewada
    @udaymewada
    I have cloned the bikeshed repo from GitHub. Is it necessary to install docker for contributing in bikeshed
    David Turner
    @dturnerx
    I hope this is the right place to post help questions. I'm getting inconsistent behavior with my status-ED.include and status-RD.include files. They show up properly for some specs, but not for others. I've verified that Status is either ED or RD. Is there another parameter I'm missing?
    Tab Atkins Jr.
    @tabatkins
    Hm, the boilerplate files are included based solely on the Group and Status metadata. Can you point to some examples that don't work?
    David Turner
    @dturnerx
    I thought it was that simple. I'll double-check (again!). I can't point you to examples because they're in private repos (for the FIDO Alliance).
    David Turner
    @dturnerx
    Yeah. There's something funky in my build process. Local build does it right. Auto build doesn't. Grr.
    Tab Atkins Jr.
    @tabatkins
    Is "auto build" using the api.csswg.org endpoint? If so, maybe you're relying on files that aren't committed into the Bikeshed repo?
    David Turner
    @dturnerx
    No. The strange thing is it seems to be working for other bikeshed spes. I'm sure I'm just missing something very small.
    Tab Atkins Jr.
    @tabatkins
    Huh. All right, well, let me know if you find anything - feel free to file an issue in the GH repo if there's actually something I need to fix.
    BenoƮt Alessandroni
    @balessan
    Hello guys !
    I may be dumb on this one but from : https://tabatkins.github.io/bikeshed I do not get how you build a local .bs file
    I cloned a repository containing multiple .bs files, people pointed me there, I installed bikeshed but I do not get how to build/access my builded files
    Oh ok got it
    It's the spec command
    Ahlala
    Justin Bingham
    @justinwb
    yep
    hi @balessan :slight_smile:
    Tab Atkins Jr.
    @tabatkins
    glad y'all figured it out ^_^
    David Turner
    @dturnerx
    Is there a way to add a release number to "Working Draft"? e.g., I'd like "Working Draft 01", "Working Draft 02", etc.