This document exists for two reasons. First, it is intended to help individuals understand the easiest way to contribute to MBC. The contribution process should always be as simple as possible out of respect for each person's time. As an open-source project, every second you contribute to MBC is deeply appreciated by the rest of the team. You are always welcomed to point out any opportunities for improvement.
Second, this document lays out some baseline expectations for reasonably interacting one another. In addition to the obvious reasons for doing so (like the lack of internet police), publicly writing down these expectations (and the appropriate response for the unfortunate cases when they aren't met) is vital to ensuring fair treatment of anyone involved. Also because we're not being paid enough to deal with internet trolls.
Each change to the official text of the MBC, as stored in this repo, goes through the following process. Capitalized words have specific definitions that are explained in later sections of this file.
- A Researcher, Developer, or Writer opens a new Issue.
- Anyone may informally comment on the Issue.
- A Developer or Writer responds to the Issue by creating a Pull Request.
- A Reviewer may need to approve the Pull Request before it's merged.
- A Developer or Writer with the necessary permissions merges the Pull Request and closes the related Issue.
If you've used Github before, then you can skip straight to the "Roles" section below.
If you've never used Github before or would like a refresher, then think of it as Google Drive, but with better tracking of how things change, who changed things, when they changed things, and who can change things. Unless you'd like to stick to email (which is fine, up to a point), you'll need to create an account.
If you've never used Google drive before (we don't judge), then think of it as something like the following. You and your friend are writing different versions of the same report (two "branches" of the same "repository") together. But imagine that you had a very good assistant (Github) who would tell you exactly how your two versions are different (a process called "version control"). Not only that, but they would also put sticky notes in your copy every time your friend noticed something that needs to be done (an "issue") or suggested a change (a "pull request").
There are some words or phrases that are very specific to Github that you'll see a lot. Here's a quick summary of them:
- repository: the database of files and folders you see when you go to this link
- branch: a parallel version of a repository. It is contained within the repository, but does not affect the primary or master branch allowing you to work freely without disrupting the "live" version. When you've made the changes you want to make, you can merge your branch back into the master branch to publish your changes. For more information, see "About branches."
- fork: a personal copy of another user's repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original. Forks remain attached to the original, allowing you to submit a pull request to the original's author to update with your changes. You can also keep your fork up to date by pulling in updates from the original.
- issue: any one of the things that need to be done at this link
- commit: a change to any file
- pull: to bring an update in to the repository
- pull request: something that someone wants to formally add to the repository. They can be viewed here
- merge: when a pull request is approved and made a part of MBC, we say that the code is merged
Here's the full list of Github terms.
Feel free to contact me at patrick@alumni.ucla.edu if you would like to fill one or more of the roles outlined below.
Being a researcher is easier than it sounds. Here are a few ways to bring new data to MBC:
- send one of us an email
- post a comment in response to one of the open issues
- open a new issue of your own to point out something to add to MBC
- you can even open a new issue in response to a specific part of the code
This can be as simple as sharing your perspective on one aspect of MBC (technical or non-technical) or as complex as sharing a new mathematical model. As outlined more thoroughly in the wiki here, everyone has something to contribute to MBC. This simple and effective way of writing a legal code is even used by Washington D.C.
If you have some expertise or experience related to some technical content in MBC, you may be interested in making sure that our building code makes sense. There are different levels of formality built into Github to allow people to review contributions.
- informally comment on an issue or on an open pull request
- formally be an assigned reviewer
Generally speaking, the informal path is the quickest and easy way to review. However, it does require other contributors to take your advice into consideration and write (or re-write) accordingly.
The formal path takes a little more time, but it also carries more weight for the reviewer. As a reviewer, a contribution may need your approval in order for it to become official. Reviewers ideally have technical expertise in the area related to the subject that they're reviewing. There are even ways to require that a complex contribution be approved by multiple people.
If you are interested in deciding how MBC grows in the big-picture sense, then this is the role for you. A developer should be involved in:
- shaping the technical content of MBC
- helping better define and improve how the team writing MBC operates
[This is, as of January 2019, the most amorphous role to describe here. Needs more!]
Do you enjoy writing good code, feel compelled to improve already-written code, or have a passion for transforming profound research into practical recommendations for building structures off-planet? If so, then create a pull request.
[Needs more content as of January 2019, too.]
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
- using the slug as the unit of mass
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at patrick@alumni.ucla.edu. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4
This message will self-destruct.