Git Product home page Git Product logo

wca-documents's Introduction

WCA Documents Build Status

Official Documents of the World Cube Association.

Process

Whenever changes are made, GitHub builds PDF files out of each Markdown document, pushes the generated files to the build branch and deploys them to the website. Documents in documents then become available at worldcubeassociation.org/documents/[path to doc].pdf, and documents in edudoc become available at worldcubeassociation.org/edudoc/[path to doc].pdf. Pre-rendered PDFs are simply copied into build during the build process.

Example: documents/policies/external/Competition Requirements.md gets converted to PDF and becomes available at https://documents.worldcubeassociation.org/documents/policies/external/Competition Requirements.pdf.

Scripts

Run these scripts from the root directory of the repository:

Script Description
bin/install_dependencies.sh Installs dependencies necessary to generate PDFs*. Run this once.
bin/build.sh Builds PDF files into the build directory. documents or edudoc can be passed as the first argument to only build documents from the specified directory.
bin/docker_build.sh Builds PDF files using Docker. Use the --rebuild flag if you need to rebuild the image. The same directory argument as in build.sh is also supported.
bin/deploy.sh WCA deployment script used by GitHub. You don't need to use this.

* This only supports Debian-based distributions. If you are not using a Debian-based distribution, install these dependencies manually: pandoc, weasyprint, Liberation Sans font, a font with full Unicode support (e.g. Google Noto).

Writing and translating documents

This document explains everything necessary to create a new document or translate an Educational Resources document.

Detailed Explanation

The build script (bin/build.sh) works in the following steps:

  1. Remove old build folder if it exists and create a new one.
  2. Copy the documents folder into build (all changes are applied inside of the build folder).
  3. Replace all occurences of wca{[url]} and wcadoc{[url]} with the actual URL to the website (used as a shortcut).
  4. Replace all occurences of {logo} with the actual absolute path to the WCA logo in assets/WCAlogo_notext.svg (used as a shortcut).
  5. Convert all Markdown files to HTML, while applying the styling in assets/style.css. HTML files are created and put next to each corresponding Markdown file.
  6. Convert all temporary HTML files in documents to PDF. PDF files are created and put next to each corresponding Markdown file.
  7. Repeat steps 2-5 for the edudoc folder, except with the use of the stylesheet in assets/edudoc-style.css.
  8. For each edudoc create a custom header using assets/edudoc-header.html, where DOCUMENT_TITLE is replaced with the actual title, WCA_LOGO_PATH is replaced with the absolute path to the logo and DATE is replaced with the current date at the time of the build.
  9. Repeat step 6 for the edudoc files, except also apply the custom header and a footer that shows the document page.
  10. Delete all non-PDF files and all empty folders in build.

wca-documents's People

Contributors

albertopdrf avatar blake98x avatar c-goodyear avatar cubewhiz avatar danielegdal avatar dmint789 avatar edhollingdale avatar emattos1723 avatar epride avatar finnickler avatar gregorbg avatar jfly avatar jonatanklosko avatar jonesparaz avatar kerriejarman avatar leonopulos avatar lgarron avatar lnzainn avatar moralsh avatar nanush7 avatar notrichardpeng avatar nsilvestri avatar ojcubing avatar pranav-027 avatar samuel-baird avatar saranshgrover avatar viktorzenk avatar viroulep avatar walkerwelch avatar zekemackay06 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

wca-documents's Issues

Require Regional Organizations to be Legal Entities

This is becoming more important as Regional Organizations are given more responsibilities and rights, especially financially.

The Board discussed a deadline of 12/31/2020 for existing organizations to comply.

Where did our GITHUB_TOKEN come from?

I looked at the list of personal access tokens for thewca-bot (https://github.com/settings/tokens), and I didn't see anything specifically for this repo. @jonatanklosko, do you know how you generated this token? Is it possible you created a token on your personal github account? Or maybe reused one of the existing tokens on thewca-bot?

I think it would make sense to instead use a token dedicated to wca-documents, so I went ahead and generated one for this project. I'll send in a PR switching this repo to use it.

Remove Silent Spring from the list of acceptable names

The WCAT believes that a competition name based solely on the competition events leaves the name too generic (although that in combination with location, for example, leaves a more unique name). This can lead to many competition in many locations being called the same thing. For instance a competition named: "Please Be Quiet 2019". Should we just allow this name to be taken from the first delegate who wants it? It's much better to add the location to the name in these cases.

Proposal, Remove:

Silent Spring 2017 (competition is named after the events)

Remove Example Proximity Exception

Remove this line from the Competition Proximity Policy as it is not an (strong) argument that is acceptable for a proximity collision exception

c. In the last 12 months, there have been fewer than 16 competitions in the area 100 km around the competition.

or change 16 to a more reasonable number like 8 (WCAT opinion).

Internal vs. External Policies

I'd like to see a way to label policies as Internal or External and have them placed separately on the website. For example, I think 99% of people do not need to read the Expense Reimbursement Policy, Dues System Policy, or Sponsor Acknowledgements Policy because they apply to organizers/Delegates only. We should do our best to keep the information on the website relevant to our readers.

Naming of staff vs external staff

(this is slightly related to #23)

I think it's really confusing that "external staff" is not a kind of "staff". This doesn't not feel intuitive to people familiar with English. I'd really love to rename these terms if possible. Here are some proposals:

Proposal 1

  • Rename "staff" to "internal staff"
  • Leave "external staff" as "external staff"
  • Now, "staff" means "someone who is either an internal staff member or an external staff member"

Proposal 2

  • Leave "staff" as is
  • Rename "external staff" to something else. Maybe "consultant" or "external worker" or "external helper"?

Are we sure we want to put all environment variables in our Repository settings?

I was trying to find out where WCA_HOST (used in deploy.sh) is defined, and it took me a while to find that it's defined over in https://travis-ci.org/thewca/wca-documents/settings. What's even weirder is that I can't actually see the value of the variable, it's just some dots:

image

I'd argue that this is perfectly safe to put in our .travis.yml file.

https://docs.travis-ci.com/user/environment-variables/ has some advice about where to put environment variables, and I feel like $WCA_HOST falls under the category of "if it does not contain sensitive information, might be different for different branches and should be available to forks – add it to your .travis.yml".

Remove Competition Announcement Policy

The Competition Announcement policy is no longer relevant because of Motion 10.2019.1, which officially establishes the Competition Announcement Team as a Motion.

Increase minimum time of physical record keeping

The guidelines asks delegates to keep physical records for at least on month (see 1c3++). This seems a very short time. WDC's investigation would be easier if delegates kept records for a longer time rather than just relying on photos. My suggestion is 2 years. I know this can be a lot of paper to keep.

Clarify Leader selection voting procedure

From an email thread with Leaders and Seniors:

So, it seems like the popular opinion is:

  • Keep the option to abstain
  • Vote needs >50% participation to be valid
  • 50% of votes cast must be affirmative for vote to pass

Document Archive

There should be an archive of old documents for historical purposes.

We have already replaced/updated some motions, but I think the old documents should exist somewhere. In the documents themselves, though, there should be a note at the top (perhaps in bold red letters) saying something like - "Outdated Document - Replaced by xxx"

I imagine that some policy documents may eventually be replaced with new versions, too. In that case, the old version should be archived with such a note when the new version is implemented.

For now, I think at least the old Motions that were replaced should be created and archived somewhere.

Update Motions related to Competition Requirements Policy

Motion 19.2017.1 Regulations and Guidelines should probably mention the Competition Requirements Policy as it relates to making competitions official.

Motion 10.2019.1 WCAT Motion needs to be updated:
2.1.3 WCA Competition Proximity Policy will be defunct
2.1.4 optional Regulations are no longer Regulations
2.1.4 Approving (and rejecting)... ?

WCRP, Main Events

WCAT and WRT has already been requiring this, so it should be represented in the WCRP:

7.3.1 The main event should be the main focus of the competition by being recognizable in the competition schedule and having an appropriate proportion of rounds and attempts.

Create a new Delegate position: Trainee Delegate

From Kit:

These types of delegates would have the following differences from a candidate delegate:

  • Have a fixed term appointment of 1 year. At the end of 1 year, their position ends unless they are further appointed to be candidate delegates, or the position is extended with full board approval (this should ideally be avoided).
  • Trainee delegates can be promoted to a candidate delegate at any time before that 1 year expires.
  • Trainee delegates can only be listed delegates at a competition with at least 1 other co-delegate that is at least at the level of a candidate delegate.
  • The trainee delegate position is optional and appointments directly to candidate can be made, but there should be a good reason for doing so.
  • Delegate in new region with few other delegates around to co-delegate.
  • Clearly has already had a high level of experience (over time this should be less common as trainees are used more often).

Many regions already use a trainee system informally, giving them the de facto delegate role at the competition to make calls on incidents under the supervision of an appointed delegate. Not only would having the trainee position formalize this role, but it would also give potential candidates exposure to the inner workings of the WCA like access to work on results, reports, and competition announcements, and give them exposure to the level professionalism and hard work expected of WCA officials. I think this is especially important for those younger candidates that show a lot of potential and passion for cubing but may not yet have a full understanding of the depth of responsibility required as a delegate. I think this also further defines a smoother trajectory into being a delegate and will increase our quality of delegates in the long run.

Some missing definitions/clarification in defintions

Officer

https://github.com/thewca/wca-documents/blob/master/documents/motions/02.2018.1%20-%20Definitions.md says Staff include "Officer", but "Officer" is not defined anywhere in the doc. @AlbertoPdRF says "officer" is defined in the bylaws, but I think our definitions doc should also define the term, or at least link to the bylaws for any missing definitions.

External Staff

External Staff An appointed External Staff Member of the WCA who performs activities for the WCA.

This definition sends me in circles. An external staff member is an external staff member who performs activities?

Z4+ limits competitor numbers when "best n competitors" is used.

I think Z4+ is quite clear on what kinds of results can be used for a qualification requirement. In major competitions there has been increased use of the "Best N ranked competitors" qualification rule, particuarly for Multi and FMC. When there are limited resources (e.g. a room that will only fit 180 FMC competitors) you want to allow as many as possible to compete, and for these to be the best competitors possible.

An issue arises when determining the final number - since either single OR average can be used. If a limit is set on average, but it is not reached, then people who just have a single would not be able to compete (assuming there are enough people who have never achieved a result in the event to push the signed up numbers over the limit). This seems unfair as there are some competitors who have a measurably better skill level (an official single compared to no result).

Equally, if the limit is more than reached by sign ups, you have the problem of determining what to do in the cases of ties. If there are 10 people ranked equal 171th of a 180 limit, then none of them would be able to compete, even though we have single results that could act as a tiebreaker.

Proposal:
I think an addition of Z4++ along the lines of "The organization team may use a second type of result in the respective event in the case of equal results in the preferred result (e.g. using best single as a tiebreak when best average is equal)."

WCRP, Event Additions

WCAT discussed to have more transparency added regarding when we allow event additions. We came with the following suggestion:

7.4 An additional event may be added upon the WCA Delegate's request at the discretion of the WCAT. The competition must meet the following requirements for an additional event to be added:

7.4.1 The competition is at least 7 days away.
7.4.2 A registration period for the competition must have a minimum of 72 hours before it closes.
7.4.3 The competitor limit must not be completely filled.

Background: This gives more fairness to the competitors who may have originally not registered for a competition due to the event list.

Security: Can we restrict Travis's user to *only* being able to run `deploy.sh` on the production server?

Currently, if someone compromises this repository and is able to decrypt the ssh private key, that person then is able to ssh to our production server and do anything.

I think it would be good to use this ssh feature: https://stackoverflow.com/questions/402615/how-to-restrict-ssh-users-to-a-predefined-set-of-commands-after-login to restrict the Travis user to only being able to run deploy.sh on our production server. That way if someone compromises this repo or decrypts the private key somehow, they aren't able to do much to our production server.

I think implementing this would just require adding the commands= bit to our authorized_keys file over in https://github.com/thewca/worldcubeassociation.org/blob/ae3c915762a8e7c7d1ea14c78d795bb91170ddbb/chef/site-cookbooks/wca/templates/gen-authorized-keys.sh.erb#L18-L23.

@jonatanklosko, does this make sense/sound reasonable? If so, I'll attempt to take care of it later this week.

WRCP 10.1 - Change Early Submission

The organization team may request to require competitors to submit puzzles at a specific time before an event is scheduled to begin.

I would suggest to change this to something like:

The organization team may request to require competitors to submit puzzles at a specific time before an event is scheduled to begin or before the competitor is required to compete.

This would encompass times when the organization team (IMO unfairly) requires all competitors to submit cubes for a Head-to-Head final at the beginning. We can evaluate these on a case by case level to see if it is even necessary to submit early, or submit whenever the competitor is called to compete.

WCA Competition Name Policy | Character Type

The competition name must be in Roman letters and may only contain characters from A-Z, a-z, and 0-9, with or without accents. Only ’.:-& are permitted as special characters.

In practice this is what is followed:

The competition name must be in Roman-readable letters and may only contain characters from A-Z, a-z, and 0-9, with or without accents. Only ’.:-& are permitted as special characters.

Feedback on Code of Ethics v1.0

#67
Code of Ethics v1.0
#69
Fix formatting error in Code of Ethics v1.0

Feedback is welcome here for the Code of Ethics. It would be preferred to leave comments and feedback here and not back another issue.
Thank You!

WCRP, Universal Registration Requirements

This was shortly mentioned in the annual staff meeting and seemed to have great support. WCAT came with the following suggestion:

6.1.3 If the registration requirements are not possible to be fulfilled by an individual due to reasons outside of their control, the Delegate must provide an alternative approach to fulfilling the requirements.

6.1.3.1 Example: A competitor with a credit card not supported by the payment platform may instead be allowed to pay at the venue on the competition day with approval from the Delegate.
6.1.3.2 Example: Not having enough money to pay the registration fee does not qualify for 6.1.3.
6.1.3.3 Example: Missing the registration deadline does not qualify for 6.1.3.

Background: Some competitors might not be able to attend a competition due to issues outside of their control.

Update Dues System Policy to include scope for Regional Organisations

Seeing the updates to the Dues System Policy (v1.2) made me think of additional detail that could be added to the policy to reflect how WCA Dues are handled for regional organisations.

2.1 makes it clear that the paying of the dues can be done by an organisation, but it is ultimately the responsibility of the WCA Delegate(s). In practice, Speedcubing Australia Inc. is invoiced for all competitions that take place in Australia - this works extremely well as a system and suits us!

Personally, I think it would be good if the role regional organisations can play is recognised in a later version of the policy. Responsibility for payment could ultimately rest on the regional organisation itself, so long as it is recognised by the WCA and has approval by all the region's delegates to act on their behalf in financial matters.

Proposal: remove word "sport" from objectives motion

The Objectives motion 1.1 reads "To act as the world governing body for the sport of Speedcubing". Without wanting to weigh in on whether or not cubing is a sport or not, I'd prefer to not explicitly state it as such.

My reasoning is purely financial; in Australia we already have quite high public liability insurance coats, and these would increase dramatically if Speedcubing Australia were to be classified as organising sport.

Allow for Sub-Regional Organizations

Some organisations (e.g. Spain) recognise/list sub-regional organisations. Should something like this be added as a right of the regional organisation in the motions? If the WCA continues to grow regional organisations may play a bigger role in organising and regulating competitions within areas. If this is the case they may also want to have scope for recognising their own sub-regional organisations.

There would be lots of things to work through if this were the case. Such as, should these sub-ROs have rights and duties recognised and regulated by the WCA as well?

WCRP, Scorecards

Jacob pointed this out, which WCAT agreed with:

8.2.2.3 Physical records (e.g. score sheets, written solutions from 3x3x3 Fewest Moves) must be retained for a minimum of 90 days. Digital records (e.g. scramble sequences, results) must be retained for 7 years. Physical records should be kept as long as possible to ensure data accuracy upon any disputes that happen after 90 days.

"Background: WCA has always had some issues due to Delegates not keeping scorecards longer which results in missing data, duplicate data, or incorrect data. This reminder should help them keep records longer which may help reduce these types of incidents."

WCRP, Deadlines for registration updates

It is often not clear which competitions allow event additions after registration has officially closed. It should be stated in the registration requirements when the deadline is to edit your registered events.

My proposal:

6.3 The deadline for updating registered events for competitors with completed registrations must be outlined.

6.3.1 This deadline will either be at the same time as registration closes or after registration has closed.

6.3.1.1 The deadline may be set to be just before an event is scheduled to take place.

6.3.2 Competitors may choose not to compete in an event they are registered for.

Is it possible to simplify the way we store our private key?

This is somewhat related to #2, but I wanted to file a separate issue to discuss it.

Currently, it looks like we have a .travis/deploy_rsa.enc file that we encrypted offline using openssl, and then committed to our repository. Then, when travis runs, it needs to decrypt that file, but to decrypt that file, it needs a secret! So, we put that secret over in our repository settings (https://travis-ci.org/thewca/wca-documents/settings).

Can we avoid the double decrypt here and instead store the encrypted version of .travis/deploy_rsa.enc directly in our .travis.yml as an encrypted environment variable (https://docs.travis-ci.com/user/environment-variables/#defining-encrypted-variables-in-travisyml)? That way, travis will handle the decrypting for us, which feels simpler to me.

Define "Policy" in Definitions

Policy is not defined anywhere in our Motions and we have several of them. We should add it to the Definitions Motion at least.

Update Finances Motion

Changes to make to WCA Motion 11.2019.1:

  1. [Section 7.1] Append "If deemed necessary by the WCA Board," to the beginning of that statement.
  2. [Section 10] Filing
    1. [Section 10.1] The WCA Financial Committee shall deliver to the WCA Board of Directors the annual returns to be filed, both on a state and federal level, at least 30 days prior to the date they are due to be filed.
    2. [Section 10.2] Upon approval of the WCA Board, the WCA Financial Committee shall file any necessary returns on behalf of the WCA.
    3. [Section 10.3] The WCA Financial Committee shall publish any returns open to public inspection and an annual financial report on the WCA website.

Forbid Logo's in Staff Email Signatures

Staff email signatures should not contain logo's as if sent to a non-WCA address a WCA logo will automatically be attached. This change should be made in the WCA Email Account Policy.

Allow WCAT Leader to Cancel competitions

Update Motions to allow WCAT Leader to cancel competitions. This is useful if canceling the competition is urgent and the WCA Board cannot be reached.

There may be places in which the language needs to be clarified after this change (WCRP?).

WCRP - Dealing with proceeds going to charities

Make it mandatory that if proceeds are going to a charity, that needs to be displayed on the competition page. Any such charity must be registered as such in the country where the competition is being held.

Having this displayed in the "Information" would probably be best since it is then not able to be edited by the Delegates/Organizers after announcement. This can be nested under "Optional requirements"

Code of Conduct

I'm going to be leading an effort to create a Code of Conduct for the WCA. I have the following rough outline in mind, although I expect that we will need to be adapt it to WCA needs:

  • Behaviour
    • We want a community that is welcoming and safe for everyone.
    • Specify what constitutes welcoming behaviour, and what does not.
  • Processes
    • If anyone reports that something/someone is making them feel unwelcome in the community, we will take it seriously and take actions to address it.
    • If someone is making others feel unwelcome in the WCA Community through any kind of actions:
      • We will ask them to be aware of the impact of their actions and change their behaviour.
      • Beyond a certain threshold, they will be banned from WCA activities (e.g. online forum participation, attending competitions).

At the moment, I'm scheduling a video meeting with members of the WRC, WAC, WDC, and WEC to assemble the team responsible for this. We may draft an initial revision in private, but I want to make sure there is time for public feedback before we finalize anything.

WCRP Update Umbrella October 2019

WCAT has discussed a series of changes. A thread will be opened for all points so we can fully discuss them. For WCA Staff, you can have a look at the document we used for internal discussion: https://docs.google.com/document/d/18q_xv86_cQynytiLynL4_hhqr2g-jgEYtXXvxiXPdhM/edit?usp=sharing

  • Universal registration requirements. #112
  • Event additions. #113
  • Main event. #114
  • Scorecards. #115
  • Grammar update of 8.2.2.2.1. (looks to be solved together with #110)

These are necessesary to be addressed as well, but WCAT skipped these when we initially drafted the above points:

  • Dealing with proceeds going to charities. #108
  • Clarify competitor limits per event. #104
  • Clarify competitor limits per location for FMC Simultaneous competitions. #116
  • Clarify waiting lists. #118
  • Clarify deadlines for updating registrations #119

WCRP- Competitor Limits Per Events

Right now we have

5.2 If the competitor limit for a competition or an event is reached before the competition, the organization team must not approve any additional registrations for the competition or the event.
5.3 The competitor limit is per competition. Per day competitor limits are not allowed

5.2 would imply that comeptitor limits per event are allowed, while 5.3 would imply they are not allowed. One of these two should be fixed based on if we wish to allow them or not.

Just a side comment: if limits per event are allowed, I think that combining a competition comeptitor limit and limit per event would make sense (ie 100 competitors total, limit of 20 for fmc due to seating).

WCRP, Waiting lists

As been outlined on certain threads, it is too different with how waiting lists are handled and it is not clear what policies are followed at different competitions. I see two solutions:

  • Ask all competitions to set a deadline for the last possible time to be added to the list of accepted competitors, if you are on the waiting list. As a default, this would be once registration closes, but may be longer than that.
  • For all competitions, simply just not allow waiting lists lasting longer than once that registration has closed.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.