👋🏽 Welcome

Welcome to the home of wg-macros! This working group is focused around implementation/design of the Rust macros.

You can learn more by reading our charter and our MCP.

🛠️ Getting involved

We have several meetings throughout the month. Feel free to stop by then (or any time!) to introduce yourself. We take meeting notes and keep them on our HackMD and look for macro tags.

If you're interested in fixing bugs, though, there is no need to wait for the meeting! Take a look at the instructions here.

We are actively working on bringing the macros vision to reality, so there are lots of ways to help. Check out the Roadmap to see the various things we are working on. Each of the high level goals should have further instructions for how to get starting helping with that goal in particular. Look for the 🛠️ icon, which highlights areas where further how to help resources are available.

Zulip

We hold discussions on the #wg-macros stream in Zulip

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Charter

TODO: See https://github.com/rust-lang/wg-macros/issues/2

🔍 Triage meetings

When, where

Currently are held on Fridays at 16:00 UTC, but see the Rust calendar rust-lang/calendar for the most up to date information, and watch #wg-macros for last minute changes.

So you want to fix a bug?

If you're interested in fixing bugs, there is no need to wait for the triage meeting. Take a look at the mentored macros bugs that have no assignee. Every mentored bug should have a few comments. If you see one you like, you can add the @rustbot claim comment into the bug and start working on it! Please only claim issues that you are actively working on. If you claim an issue and then realize you don't have time to finish it, that's totally fine! Just remember to release it in that case.

Project board

We do not have a Project board yet

Triage process

In our bi-weekly triage meetings, we take new issues assigned with a macros label and categorize them. The process is:

• Review [uncategorized issues]
  • Mark P-low, P-medium, or P-high
  • Add P-high and assigned E-needs-mentor issues to the [project board]
  • Mark triaged
• If there's still a shortage of To do issues, review the list of P-medium or P-low issues for candidates

Mentoring

If an issue is a good candidate for mentoring, mark E-needs-mentor and try to find a mentor.

Mentors assigned to issues should write up mentoring instructions. Often, this is just a couple lines pointing to the relevant code. Mentorship doesn't require intimate knowledge of the compiler, just some familiarity and a willingness to look around for the right code.

After writing instructions, mentors should un-assign themselves, add E-mentor, and remove E-needs-mentor. On the project board, if a mentor is assigned to an issue, it should go to the Claimed column until mentoring instructions are provided. After that, it should go to To do until someone has volunteered to work on it.

🔮 The vision

What is this

This document is a collaborative effort to build a shared vision for Macros in Rust. Our goal is to engage the entire community in a collective act of the imagination: how can we make the end-to-end experience of using macros a joyful one?

🚧 Under construction! Help needed! 🚧

The first version of this document is not yet complete, and we are working on it! We are in the process of understanding what we want to do as a working group, so if you want help please reach out.

Involving the whole community

The macros vision document provides a forum where the rust community can plan a great overall experience for users.

❓ How to vision

How you can help

Making the vision real

We are currently working towards implementing the macros vision described in this website. If you'd like to participate in an initiative, you can find the appropriate Zulip stream and see if they are looking for help!

Goal and initiative owners

Each top-level goal and initiative in the roadmap has an owner. The owner of the top-level goal manages the goal overall, while the owner of an initiative manages the "nitty gritty" design work (for example, preparing the evaluation, authoring any RFCs required, or supervising the implementation). You can learn more about the responsibilities of owners in this page. If you have questions about whether you can help out with a goal or an initiative, the owner is probably the one to talk to.

Help wanted goals

Some of the top-level goals are marked with ✋, which means "help wanted". Those goals are looking for an owner. If you think you might be interested, you can read about the responsibilities of owners and contact the wg leads.

Owning a goal or initiative

This page describes the roles and responsibilities associated with being the owner of an item on the roadmap. Roadmap items fall into two categories, top-level goals and initiatives. In both cases, being an owner means that you are responsible for ensuring that the item gets done, but the details of owning a top-level goal are different from owning an initiative.

Summary

Goal owners are responsible for splitting their area into a set of initiatives. These can be active or on hold.

They are also responsible for ensuring that for each initiative:

• An owner is assigned
• A landing page exists
• Milestones are defined on the landing page

Finally, they are expected to attend wg meetings.

WG meetings

We are organizing the working group in weekly meetings. This means that every weeks we have a open discussion meeting. All goal owners are expected to attend! Initiative owners or other contributors are welcome as well.

The purpose of the sprint planning meeting is to check-in on the progress towards the milestones for each initiative and to see if they need to be adjusted. It's also a chance to raise interesting questions or get advice about tricky things or unexpected problems, as well as to celebrate our progress.

Owning a top-level goal

As the owner of a top-level goal your role is to figure out overall plan for how that goal will be achieved and to track progress. This means breaking up the goal into different initiatives, finding owners for those initiatives (which can be you!), and helping those owners to plan milestones. You are also generally responsible for staying on top of the state of things and updating other owners as to new or interesting developments.

Owning an initiative

Our definition of initiative is precisely the same as that used by the Rust lang team: it corresponds to a some active effort with a clear goal or deliverable(s). As the owner of an initiative, your role is to ensure that the work gets done (Which doesn't necessarily mean you do it yourself, it may be that you instead coordinate with volunteers or other implementors). You also guide the design of the deliverables within the initiative.

As in the lang team process, the role of the owner is not to make the final decision (that belongs to the relevant rust team(s)), but to develop the "menu" of design choices, elaborate the tradeoffs involved, and make recommendations. For particularly complex designs, these evaluations will take the form of evaluation documents and are developed in collaboration.

Making a landing page

Each initiative should have a landing page, linked to from the roadmap. This can be a page on this website or a dedicated repo.

For in-progress initiatives the landing page should include, or have pointers to:

• Goals and impact of the initiative
• Milestones
• Design notes and documentation
• Links to any organizing tools, such as a project board
• The initiative owner
• Notes on how to get involved
• For landing pages not on this website, a link back to the overall roadmap

For making a dedicated repo, it's recommended to use this initiative template as a starting point.

Planning initiative milestones

When you own an initiative, you should work with the owner of the top-level goal and others to plan out a series of milestones around the initiative. These milestones correspond to the various steps you need to take to complete the initiative.

Milestones are not fixed and they frequently change as you progress. They usually start out quite vague, such as "author an RFC", and then get more precise as you learn more about what is required: "figure out the design for X", "implement feature Y". We update the status and set of milestones for each sprint status meeting.

❓ How to vision: Constructive comments

Figuring out the future is tricky business. We all know the internet is not always a friendly place. We want this discussion to be different.

Be respectful and supportive

Writing a "status quo" or "shiny future" story is an act of bravery and vulnerability. In the status quo, we are asking people to talk about the things that they or others found hard, to admit that they had trouble figuring something out. In the case of the shiny future, we're asking people to put out half-baked ideas so that we can find the seeds that will grow into something amazing. It doesn't take much to make that go wrong.

Comment to understand or improve, not to negate or dissuade

“Most people do not listen with the intent to understand; they listen with the intent to reply.”

-- Stephen Covey

The golden rule is that when you leave a comment, you are looking to understand or improve the story.

For status quo stories, remember that these are true stories about people's experiences -- they can't be wrong (though they could be inaccurate). It may be that somebody tries for days to solve a problem that would've been easy if they had just known to call a particular method. That story is not wrong, it's an opportunity to write a shiny future story in which you explain how they would've learned about that method, or perhaps about how that method would become unnecessary.

For shiny future stories, even if you don't like the idea, you should ask comments with the goal of better understanding what the author likes about it. Understanding that may give you an idea for how to get those same benefits in a way that you are happier with. It's also valid to encourage the author to elaborate on the impact their story will have on different characters.

You might just want to write your own story

Remember, opening your own PR if you find that you had a really different experience than a status quo story, or you have a different idea for a shiny future, consider just writing your own PR instead of commenting negatively on someone else's. The goal of the brainstorming phase is to put a lot of alternatives, so that we can look for opportunities to combine them and make something with the best of both.

Good questions for status quo stories

Here are some examples of good questions for "status quo" stories:

• Tell me more about this step. What led NAME to do X?
• What do you think OTHER_NAME would have done here?
• Can you be more specific about this point? What library did they use?

Good questions for shiny future stories

Here are some examples of good questions for "shiny future" stories:

• How does NAME do X in this future?
• It seems like this would interfere with X, which is important for application A. How would NAME handle that case in this future?

You should not be afraid to raise technical concerns -- we need to have a robust technical discussion! But do so in a way that leaves room to find an answer that satisfies both of you.

⚡ Projects

What is this?

This section describes various sample projects that are referenced in our stories. Each project is meant to represent some domain that we are targeting.

List of projects

See the sidebar for the full list.

Don't find a project like yours here?

Don't despair! This is just a list of fun projects that we've needed for stories. If you'd like to add a project for your story, feel free to do so! Note though that you may find that some existing project has the same basic characteristics as your project, in which case it's probably better to reuse the existing project.

⚡ Projects: NAME (DOMAIN)

This is a template for adding new projects. See the instructions for more details on how to add new project!

What is this?

This is a sample project for use within the various "status quo" or "shiny future" stories.

Description

Give a fun description of the project here! Include whatever details are needed.

🤔 Frequently Asked Questions

What makes this project different from others?

Does this project require a custom tailored runtime?

How much of this project is likely to be built with open source components from crates.io?

What is of most concern to this project?

What is of least concern to this project?

Roadmap

Each goal has associated initiatives, which are particular streams of work within that goal. Each goal and each initiative have an associated owner -- in some cases multiple owners -- who are the people responsible for ensuring that the goal/initiative is making progress. If you click on a goal/initiative, you will get a high-level description of its impact. That is, how the experience of using macros is going to change as a result of this work.

We categorize the goals and initiatives into four states:

Some goals and initiatives have further "how to help" instructions for those wanting to contribute. These are marked by the 🛠️ symbol.

Overview

🔬 Design documents

The design documents (or "design docs", more commonly) describe potential designs. These docs vary greatly in terms of their readiness to be implemented:

• Early on, they describe a vague idea for a future. Often this takes the shape of capturing constraints on the solution, rather than the solution itself.
• When a feature is getting ready to ship, they can evolve into a full blown RFC (see the procedure to propose an RFC), with links to tracking issues or other notes.

Early stage design docs

In the early stages, design docs are meant to capture interesting bits of "macros design space". They are often updated to capture the results of a fruitful conversation or thread which uncovered contraints or challenges in solving a particular problem. They will capture a combination of the following:

• use cases;
• interesting aspects to the design;
• alternatives;
• interactions with other features.

Late stage design docs

As a design progresses, the doc should get more and more complete, until it becomes something akin to an RFC. Often, at that point, we will expand the design document into a directory, adding an actual RFC draft and other contents; those things can live in this repo or elsewhere. Once we decide to put a design doc onto the roadmap, it will also contain links to tracking issues or other places to track the status.

Glossary

If you follow discussions in the macros ecosystem you're likely to find acronyms being tossed around, many of which refer to language features that are in-progress. What follows is a best-effort list of those acronyms and links to resources discussing the language features.