basic Circle-CI build

[casperdcl]

Add CI tests

• fixes add CI #56
• prerequisite for automate subproject metadata parsing #55
• also builds master hourly (takes just 10 sec to build and 20 to upload the build artifacts)
• updates README.md with some basic information

Currently only tests that mkdocs build succeeds without errors.

• status: https://circleci.com/gh/openworm
• example artifacts: https://circleci.com/gh/openworm/openworm_docs/3#artifacts/containers/0
• status (this branch):
• status (master):
• status (master, shields style):
• current readthedocs: @mwatts15 any idea why this isn't green?

References:

• https://www.mkdocs.org/
• https://circleci.com/docs/2.0/gh-bb-integration/
• https://circleci.com/docs/2.0/configuration-reference/
  https://circleci.com/docs/2.0/executor-types/
• https://circleci.com/docs/2.0/circleci-images/
• https://circleci.com/docs/2.0/language-python/
• https://circleci.com/docs/2.0/artifacts/

---

• https://openworm.slack.com/apps/A0F7VRE7N-circleci
• https://docs.readthedocs.io/en/stable/webhooks.html

[mwatts15]

I'm not certain why the rtd status is unknown - for me it's green if I get it directly from the readthedocs.org. It's conditional on a cookie I have, so github's caching causes it to show as "unknown" even for me here.

General question: why Circle-CI vs Travis-CI? AFAIK, this would be the first OW project using Circle-CI, so this would introduce additional maintenance overhead to deal with two CI environments.

[mwatts15]

Circle-CI translates this config into a different format: resolves the &defaults reference and apparently inlines the "install" command. Is there an expectation that "defaults" or "install" objects will be reused to justify breaking them out?

https://circleci.com/gh/openworm/openworm_docs/4#config/containers/0
Is there

[casperdcl]

not for this PR, but potentially for addressing #55. Could remove this for now if you prefer.

[casperdcl]

General question: why Circle-CI vs Travis-CI?

After discussing with @cheelee the conclusion was that any CI which integrates well with GitHub would be fine. I also have much more experience with Travis but recently started using Circle and it seems much quicker and easier to use. For example, these builds all complete about 30s after a commit is pushed. From my experience Travis takes much longer.

I don't really have a strong preference though.

[mwatts15]

I created dev_openworm_docs because I didn't (and still don't) have maintainer-level access to https://readthedocs.org/projects/openworm/

@slarson or @travs - could you give @casperdcl and myself access?

[mwatts15]

OK. I think the write permissions requested by Circle-CI are excessive, which is part of my initial negative reaction, but since we're limiting it to this "bot", I'm OK with that as long as OpenWorm org admins get access credentials for the bot.

I'll go ahead and merge in a couple hours.

[casperdcl]

ah but the permissions (for managing e.g. webhooks) are a GitHub access level thing - the same would be required for a bot account on Travis. Unless I've misunderstood something.

Of course in both cases, org admins should get credentials.

[mwatts15]

ah but the permissions (for managing e.g. webhooks) are a GitHub access level thing - the same would be required for a bot account on Travis. Unless I've misunderstood something.

Of course in both cases, org admins should get credentials.

You are somewhat mistaken. At least by default, Circle-CI requests a broader set of permissions for writing to public repositories than Travis-CI for open source projects. This is a more recent change though (I only looked into it the other day), so you may have missed it if you set up Travis-CI access a while ago.

[mwatts15]

I just realized, @casperdcl should have all of the permissions you need to merge. So, fire when ready.

[casperdcl]

At least by default, Circle-CI requests a broader set of permissions

Ah @mwatts15 I didn't know. Are there any particular permissions we need to be concerned about?

should have all of the permissions you need to merge

Yes I know but still wanted some approval first :)

[mwatts15]

The public repo permission is the one that most bothers me:

The concern, of course, isn't that Circle-CI intentionally abuses the permission, but that Circle-CI is compromised or they make an accident. Obviously, it's only relatively more risky to use Circle-CI -- we're already using a Github which none of us really controls -- but my reasoning is that limiting permissions means a smaller chance we have to waste time fixing stuff we didn't break ourselves. 🤷‍♂️

should have all of the permissions you need to merge

Yes I know but still wanted some approval first :)

Quite right. Code review is a good thing :)

[casperdcl]

hmm.

• as an org admin, can you disable some of the Circle CI permissions? I can't actually recall giving it any of those permissions. For my personal (@casperdcl) account, I have:
  which is indeed a little deceptive as it's not explicit that "access public repositories" includes full write access. I don't think either my account or @openworm-bot had permissions to grant circle-ci access to openworm, though - think it was already that way?
• Travis can only do daily automated builds (https://docs.travis-ci.com/user/cron-jobs/) whereas we can get circle CI to run every minute if we wanted (this PR is hourly)
• contexts (sharing secure env vars, https://circleci.com/circleci-versus-travisci/) might be useful in future when dealing with other repos in the organisation (e.g. https://github.com/openworm/openworm)

[mwatts15]

I did a quick review of application access in the org and enabled some additional restrictions, but again, I think the access granted is OK in this case. My concern was more for granting access through my Github user for the sake of maintaining Circle-CI builds, but you've addressed that concern: thank you!

I think we can have Circle-CI for this, especially if it's easier to achieve what you have planned with it than with Travis-CI. We can debate which one is preferred generally elsewhere/at a later time.

[casperdcl]

fyi travis cron jobs can only be daily at most (https://docs.travis-ci.com/user/cron-jobs/) wheras with Circle-CI we can do even every minute.