diff --git a/README.md b/README.md index 4eca1360..1d4ecb7e 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,18 @@ -[![Travis-CI Status]][travis] [![UCG Book]][ucg_book] -[travis]: https://travis-ci.com/rust-lang/unsafe-code-guidelines -[Travis-CI Status]: https://travis-ci.com/rust-lang/unsafe-code-guidelines.svg?branch=master -[UCG Book]: https://img.shields.io/badge/UCG%20Book-Unsafe%20Code%20Guidelines%20Book-blue.svg -[ucg_book]: https://rust-lang.github.io/unsafe-code-guidelines - -UCG WG - Rust's Unsafe Code Guidelines Working Group +UCG - Rust's Unsafe Code Guidelines === -The goal of the UCG WG is to produce the [Unsafe Code Guidelines -Reference][ucg_book]: a "guide" for writing unsafe code that "recommends" what -kinds of things unsafe code can and cannot do, and that documents which -guarantees unsafe code may rely on. It is largely a work-in-progress right now. - -Unless we state otherwise, the information in the guide is mostly a -"recommendation" and still subject to change. The main goal for the WG in 2019 -is to RFC parts of the guide into the language specification, and move those -parts into the [Rust Language Reference] proper. - -[Rust Language Reference]: https://doc.rust-lang.org/reference/index.html - -> **note**: the instructions to build the UCG reference book are in the -> [`.travis.yml`][travis_yml] file. - -[travis_yml]: .travis.yml - -## Process - -A more complete description of our process is available in [the `process.md` -file][process]. Briefly: - -[process]: process.md +The purpose of this repository is to collect and discuss all sorts of questions that come up when writing unsafe code. +It is primarily used by the [opsem team](https://github.com/rust-lang/opsem-team/) to track open questions around the operational semantics, but we also track some "non-opsem" questions that fall into T-lang or T-type's purview, if they are highly relevant to unsafe code authors. -* **active discussion area**: At any given time, the UCG working group is - focused on one particular **area** of discussion. The current area is - [**Validity Invariants**][current_area] -- read that link for more background - and information. You can find the [active discussion threads - here][active_discussion]. +The [Unsafe Code Guidelines Reference "book"][ucg_book] is a past effort to systematize a consensus on some of these questions. +It is not actively maintained any more, but can still be a good source of information and references. +Note however that unless stated otherwise, the information in the guide is mostly a "recommendation" and still subject to change. -[current_area]: active_discussion/validity.md -[active_discussion]: https://github.com/rust-lang/unsafe-code-guidelines/issues?q=is%3Aissue+is%3Aopen+label%3A%22active+discussion+topic%22 +Current consensus is documented in [t-opsem FCPs](https://github.com/rust-lang/opsem-team/blob/main/fcps.md) and the [Rust Language Reference]. -* **communication channels**: Most of the discussion takes place here in GitHub - issues. Many of us do also hang out on [Zulip's `wg-unsafe-code-guidelines` - stream][Zulip]. There is rust-lang org team called - [`WG-unsafe-code-guidelines`][rust_team] that is commonly cc'd when curious - situations arise. Send a private message to @nikomatsakis on [internals] or - [Zulip] if you would like to be added (note: membership does not imply any - particular decision-making power). - -[Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/136281-wg-unsafe-code-guidelines -[rust_team]: https://github.com/orgs/rust-lang/teams/wg-unsafe-code-guidelines -[internals]: https://internals.rust-lang.org/ - -* **meetings**: Every Thursday at 12:15 UTC-4 (16:15 UTC), we hold a brief - _non-technical_ meeting on [Zulip] to triage issues, PRs, assign work, etc. - Everybody is welcome to attend. - -Ideas for future "areas of discussion" are represented as [issues labeled with -the "proposed discussion topic" label][proposed_discussion]. Feel free to open -more such issues if you have a question that doesn't match any of the existing -issues! - -[proposed_discussion]: https://github.com/rust-rfcs/unsafe-code-guidelines/labels/proposed%20discussion%20topic - -We follow the [Rust's Code of Conduct]. Any concerns should be addressed to the -[moderation team] immediately. - -[Rust's Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html -[moderation team]: https://www.rust-lang.org/team.html#Moderation-team +[ucg_book]: https://rust-lang.github.io/unsafe-code-guidelines +[Rust Language Reference]: https://doc.rust-lang.org/reference/index.html ## See also @@ -78,7 +22,11 @@ effort to explain how to write Rust code, rather than a reference. [Rustonomicon]: https://doc.rust-lang.org/nightly/nomicon/ -The [nikomatsakis/rust-memory-model] was a previous effort and contains a lot of -good links and information. +## Code of Conduct and licensing + +All interactions on this repository (whether on issues, PRs, or +elsewhere) are governed by the [Rust Code of +Conduct](CODE_OF_CONDUCT.md). -[nikomatsakis/rust-memory-model]: https://github.com/nikomatsakis/rust-memory-model +Further, all content on this repository is subject to the standard +[Rust](LICENSE-MIT) [licensing](LICENSE-APACHE). diff --git a/active_discussion.md b/active_discussion.md deleted file mode 100644 index 19ba1335..00000000 --- a/active_discussion.md +++ /dev/null @@ -1 +0,0 @@ -# Areas of active discussion diff --git a/process.md b/process.md deleted file mode 100644 index c4550e3d..00000000 --- a/process.md +++ /dev/null @@ -1,67 +0,0 @@ -### TL;DR - -The basic idea is simple: we try to focus discussion on one area at a -time. The discussion begins with a proposal outlining the goals ([here -is an example of such a proposal][eg]). From there, we open up various -threads that are discussing "mostly independent" topics. Over the -course of the discussion, a "discussion lead" will periodically -collate the details into a document living in the -[unsafe-code-guidelines repository][repo], so that people can get up -to speed more quickly. At some point, when we feel like we've gone as -far as we can go, we "wrap up" the discussion and select another thing -to talk about. - -[repo]: https://github.com/rust-rfcs/unsafe-code-guidelines/ - -### Starting a discussion - -To start a discussion, a lead (or group of leads) prepares a -"discussion proposal". This has the form of a PR. The basis for the -proposal is [the `TEMPLATE.md` file][template]. The idea is that this -proposal will: - -[template]: active_discussion/TEMPLATE.md - -- outline the topic to be discussed and the goals of the discussion, -- highlight some interesting questions and background reading, -- and propose an initial set of threads. - -On the PR, we can discuss whether this is a good thing to talk about -and what changes we might make. For example, maybe we want to narrow -the topic, or add some more examples. - -### Repo and Threads - -Once we decide to adopt an area for discussion (see "meetings" below), -we do the following: - -- merge the PR and update the README.md appropriately -- create a `topic-foo` label for this topic -- open the initial discussion threads, tagging them with the new label - -### Ending a discussion - -At some point, we will decide in one of the meetings (see below) that -the discussion has reached a steady state (no new points are being -made). The leads can then take the final summaries and move that -content into our "reference", which basically collates all the results -from prior discussions. Note that discussions don't have to reach firm -conclusions: it is ok to end with "these things are known" as well as -"these things need to be settled in the future". - -### Regular meetings and schedule - -In general, regular meetings are held every two weeks (the time and -venue appears in the README). Meetings are used to decide when to change -topics and so forth. - -Attendance at the meeting is welcome but not mandatory or -expected. Prior to the meeting itself, the discussion leads will open -a PR with updated summaries and a suggestion of whether to move on -etc. It is suggested that you comment on this PR. - -### Making things official - -Conclusions reached by this working group are effectively -"recommendations". To become official, they have to go through the -Rust RFC process as a lang team RFC. diff --git a/projects.md b/projects.md deleted file mode 100644 index 6cb00d3e..00000000 --- a/projects.md +++ /dev/null @@ -1,13 +0,0 @@ -# Projects related to Unsafe Code Guidelines - -## Blogs and other related discussions -* [Stacked Borrows: An Aliasing Model for Rust](https://www.ralfj.de/blog/2018/08/07/stacked-borrows.html) -* [Two Kinds of Invariants: Safety and Validity](https://www.ralfj.de/blog/2018/08/22/two-kinds-of-invariants.html) -* [An alias-based formulation of the borrow checker](http://smallcultfollowing.com/babysteps/blog/2018/04/27/an-alias-based-formulation-of-the-borrow-checker/) - - -## Code and Tools - -Any code projects related to the effort should be included here: -* [Miri](https://github.com/solson/miri) -* [unsafe-unicorn](https://github.com/avadacatavra/unsafe-unicorn): naive text-based analysis for unsafe usage