Merge remote-tracking branch 'upstream/nightly' into fix-iter-ergonomics

CONTRIBUTING.md

@@ -386,7 +386,64 @@ By making a contribution to this project, I certify that:
     this project or the open source license(s) involved.
 ```
 
-### Review time SLA
+### Guidelines for Review Time
 
-The team commits to reviewing submitted pull requests within a week of
-submission.
+1. Pull Request (PR) Review Timeline
+
+- Initial Review:
+  - Maintainers will provide an initial review or feedback within 3 weeks of
+    the PR submission.  At times, it may be significantly quicker, but it
+    depends on a variety of factors.
+- Subsequent Reviews:
+  - Once a contributor addresses feedback, maintainers will review updates as
+    soon as they can, typically within 5 business days.
+
+1. Issue Triage Timeline
+
+- New Issues:
+  - Maintainers will label and acknowledge new issues within 10 days of the
+    issue submission.
+
+1. Proposals
+
+- Proposals take more time for the team to review, discuss, and make sure this
+  is in line with the overall strategy and vision for the standard library.
+  These will get discussed in the team's weekly design meetings internally and
+  feedback will be communicated back on the relevant proposal.  As a team, we'll
+  ensure these get reviewed and discussed within 6 weeks of submission.
+
+#### Exceptions
+
+While we strive our best to adhere to these timelines, there may be occasional
+delays due any of the following:
+
+- High volume of contributions.
+- Maintainers' availability (e.g. holidays, team events).
+- Complex issues or PRs requiring extended discussion (these may get deferred to
+  the team's weekly design discussion meetings).
+
+Note that just because a pull request has been reviewed does not necessarily
+mean it will be able to merged internally immediately.  This could be due to a
+variety of reasons, such as:
+
+- Mojo compiler bugs.  These take time to find a minimal reproducer, file an
+  issue with the compiler team, and then get prioritized and fixed.
+- Internal bugs that get exposed due to a changeset.
+- Massive refactorings due to an external changeset.  These also take time to
+  fix - remember, we have the largest Mojo codebase in the world internally.
+
+If delays occur, we'll provide status updates in the relevant thread (pull
+request or GitHub issue).  Please bare with us as Mojo is an early language.
+We look forward to working together with you in making Mojo better for everyone!
+
+#### How You Can Help
+
+To ensure quicker reviews:
+
+- **Ensure your PR is small and focused.** See the [pull request size section](#about-pull-request-sizes)
+  for more info.
+- Write a good commit message/PR summary outlining the motivation and describing
+  the changes.  In the near future, we'll provide a pull request template to
+  clarify this further.
+- Use descriptive titles and comments for clarity.
+- Code-review other contributor pull requests and help each other.

docs/changelog-released.md

@@ -60,7 +60,7 @@ detailed information in the following sections:
   [`UnsafePointer`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer) instead.
   Functions that previously took a `DTypePointer` now take an equivalent
   `UnsafePointer`. For more information on using pointers, see [Unsafe
-  pointers](/mojo/manual/pointers) in the Mojo Manual.
+  pointers](/mojo/manual/pointers/unsafe-pointers) in the Mojo Manual.
 
 - There are many new standard library APIs, with new features for strings,
   collections, and interacting with the filesystem and environment. Changes are
@@ -518,7 +518,7 @@ detailed information in the following sections:
   - `DTypePointer`, `LegacyPointer`, and `Pointer` have been removed. Use
     [`UnsafePointer`](/mojo/stdlib/memory/unsafe_pointer/UnsafePointer) instead.
     For more information on using pointers, see [Unsafe
-    pointers](/mojo/manual/pointers) in the Mojo Manual.
+    pointers](/mojo/manual/pointers/unsafe-pointers) in the Mojo Manual.
 
     Functions that previously took a `DTypePointer` now take an
     equivalent `UnsafePointer`. A quick rule for conversion from `DTypePointer` to
@@ -1013,7 +1013,7 @@ Big themes for this release:
 
 - New Mojo Manual pages on [Control flow](/mojo/manual/control-flow),
   [Testing](/mojo/tools/testing) and using
-  [unsafe pointers](/mojo/manual/pointers).
+  [unsafe pointers](/mojo/manual/pointers/unsafe-pointers).
 
 ### Language changes
 
@@ -6088,7 +6088,7 @@ busy this week.
 - 📢 The `__clone__` method for copying a value is now named `__copy__` to
   better follow Python term of art.
 
-- 📢 The `__copy__` method now takes its self argument as a "borrowed" value,
+- 📢 The `__copy__` method now takes its self argument as a "read" value,
   instead of taking it by reference.  This makes it easier to write, works for
   `@register_passable` types, and exposes more optimization opportunities to
   the early optimizer and dataflow analysis passes.
@@ -6153,7 +6153,7 @@ busy this week.
   Note that `@register_passable` types must use the later style.
 
 - 📢 The default argument convention is now the `borrowed` convention.  A
-  "borrowed" argument is passed like a C++ `const&` so it doesn't need to
+  "read" argument is passed like a C++ `const&` so it doesn't need to
   invoke the copy constructor (aka the `__clone__` method) when passing a value
   to the function.  There are two differences from C++ `const&`:
 

docs/changelog.md

@@ -50,6 +50,20 @@ what we publish.
   The consequence of this is that the old hack is no longer needed for these
   cases!
 
+- Various improvements to origin handling and syntax have landed, including
+  support for the ternary operator and allowing multiple arguments in a `ref`
+  specifier (which are implicitly unions).  This enables expression of simple
+  algorithms cleanly:
+
+  ```mojo
+  fn my_min[T: Comparable](ref a: T, ref b: T) -> ref [a, b] T:
+    return a if a < b else b
+  ```
+
+  It is also nice that `my_min` automatically and implicitly propagates the
+  mutability of its arguments, so things like `my_min(str1, str2) += "foo"` is
+  valid.
+
 - The `UnsafePointer` type now has an `origin` parameter that can be used when
   the `UnsafePointer` is known to point to a value with a known origin. This
   origin is propagated through the `ptr[]` indirection operation.
@@ -110,6 +124,18 @@ what we publish.
 - The `rebind` standard library function now works with memory-only types in
   addition to `@register_passable("trivial")` ones, without requiring a copy.
 
+- Introduce `random.shuffle` for `List`.
+  ([PR #3327](https://github.com/modularml/mojo/pull/3327) by [@jjvraw](https://github.com/jjvraw))
+
+  Example:
+
+  ```mojo
+  from random import shuffle
+
+  var l = List[Int](1, 2, 3, 4, 5)
+  shuffle(l)
+  ```
+
 - The `Dict.__getitem__` method now returns a reference instead of a copy of
   the value (or raises).  This improves the performance of common code that
   uses `Dict` by allowing borrows from the `Dict` elements.
@@ -240,8 +266,10 @@ what we publish.
   of variables that are handled as synthetic types, e.g. `List` from Mojo or
   `std::vector` from C++.
 
-- Added `os.path.expandvars` to expand environment variables in a string.
-  ([PR #3735](https://github.com/modularml/mojo/pull/3735) by [@thatstoasty](https://github.com/thatstoasty)).
+- Expanded `os.path` with new functions (by [@thatstoasty](https://github.com/thatstoasty)):
+  - `os.path.expandvars`: Expands environment variables in a path ([PR #3735](https://github.com/modularml/mojo/pull/3735)).
+  - `os.path.splitroot`: Split a path into drive, root and tail.
+  ([PR #3780](https://github.com/modularml/mojo/pull/3780)).
 
 - Added a `reserve` method and new constructor to the `String` struct to
   allocate additional capacity.
@@ -250,7 +278,7 @@ what we publish.
 - Introduced a new `Deque` (double-ended queue) collection type, based on a
   dynamically resizing circular buffer for efficient O(1) additions and removals
   at both ends as well as O(1) direct access to all elements.
-  
+
   The `Deque` supports the full Python `collections.deque` API, ensuring that all
   expected deque operations perform as in Python.
 
@@ -260,8 +288,32 @@ what we publish.
   memory allocation and performance. These options allow for optimized memory usage
   and reduced buffer reallocations, providing flexibility based on application requirements.
 
+- A new `StringLiteral.get[some_stringable]()` method is available.  It
+  allows forming a runtime-constant StringLiteral from a compile-time-dynamic
+  `Stringable` value.
+
+- `Span` now implements `__reversed__`. This means that one can get a
+  reverse iterator over a `Span` using `reversed(my_span)`. Users should
+  currently prefer this method over `my_span[::-1]`.
+
+- `StringSlice` now implements `strip`, `rstrip`, and `lstrip`.
+
+- Introduced the `@explicit_destroy` annotation, the `__disable_del` keyword,
+  the `UnknownDestructibility` trait, and the `ImplicitlyDestructible` keyword,
+  for the experimental explicitly destroyed types feature.
+
+- Added associated types; we can now have aliases like `alias T: AnyType`,
+  `alias N: Int`, etc. in a trait, and then specify them in structs that conform
+  to that trait.
+
 ### 🦋 Changed
 
+- The `inout` and `borrowed` argument conventions have been renamed to the `mut`
+  and `read` argument conventions (respectively).  These verbs reflect
+  declaratively what the callee can do to the argument value passed into the
+  caller, without tying in the requirement for the programmer to know about
+  advanced features like references.
+
 - The argument convention for `__init__` methods has been changed from `inout`
   to `out`, reflecting that an `__init__` method initializes its `self` without
   reading from it.  This also enables spelling the type of an initializer
@@ -283,6 +335,24 @@ what we publish.
   release of Mojo, but will be removed in the future.  Please migrate to the
   new syntax.
 
+- Similarly, the spelling of "named functions results" has switched to use `out`
+  syntax instead of `-> T as name`.  Functions may have at most one named result
+  or return type specified with the usual `->` syntax.  `out` arguments may
+  occur anywhere in the argument list, but are typically last (except for
+  `__init__` methods, where they are typically first).
+
+  ```mojo
+  # This function has type "fn() -> String"
+  fn example(out result: String):
+    result = "foo"
+  ```
+
+  The parser still accepts the old syntax as a synonym for this, but that will
+  eventually be deprecated and removed.
+
+  This was [discussed extensively in a public
+  proposal](https://github.com/modularml/mojo/issues/3623).
+
 - More things have been removed from the auto-exported set of entities in the `prelude`
   module from the Mojo standard library.
   - `UnsafePointer` has been removed. Please explicitly import it via
@@ -319,7 +389,7 @@ what we publish.
   `String.write`. Here's an example of using all the changes:
 
   ```mojo
-  from utils import Span
+  from memory import Span
 
   @value
   struct NewString(Writer, Writable):
@@ -415,6 +485,19 @@ what we publish.
   for more information and rationale.  As a consequence the `__lifetime_of()`
   operator is now named `__origin_of()`.
 
+- `Origin` is now a complete wrapper around the MLIR origin type.
+
+  - The `Origin.type` alias has been renamed to `_mlir_origin`. In parameter
+    lists, you can now write just `Origin[..]`, instead of `Origin[..].type`.
+
+  - `ImmutableOrigin` and `MutableOrigin` are now, respectively, just aliases
+    for `Origin[False]` and `Origin[True]`.
+
+  - `Origin` struct values are now supported in the brackets of a `ref [..]`
+    argument.
+
+  - Added `Origin.cast_from` for casting the mutability of an origin value.
+
 - You can now use the `+=` and `*` operators on a `StringLiteral` at compile
   time using the `alias` keyword:
 
@@ -513,6 +596,33 @@ what we publish.
           self.value = value
   ```
 
+- `Arc` has been renamed to `ArcPointer`, for consistency with `OwnedPointer`.
+
+- `UnsafePointer` parameters (other than the type) are now keyword-only.
+
+- Inferred-only parameters may now be explicitly bound with keywords, enabling
+  some important patterns in the standard library:
+
+  ```mojo
+  struct StringSlice[is_mutable: Bool, //, origin: Origin[is_mutable]]: ...
+  alias ImmStringSlice = StringSlice[is_mutable=False]
+  # This auto-parameterizes on the origin, but constrains it to being an
+  # immutable slice instead of a potentially mutable one.
+  fn take_imm_slice(a: ImmStringSlice): ...
+  ```
+
+- Added `PythonObject.__contains__`.
+  ([PR #3101](https://github.com/modularml/mojo/pull/3101) by [@rd4com](https://github.com/rd4com))
+
+  Example usage:
+
+  ```mojo
+  x = PythonObject([1,2,3])
+  if 1 in x:
+     print("1 in x")
+
+- `Span` has moved from the `utils` module to the `memory` module.
+
 ### ❌ Removed
 
 - The `UnsafePointer.bitcast` overload for `DType` has been removed.  Wrap your
@@ -544,6 +654,21 @@ what we publish.
 - [Issue #3710](https://github.com/modularml/mojo/issues/3710) - Mojo frees
   memory while reference to it is still in use.
 
+- [Issue #3805](https://github.com/modularml/mojo/issues/3805) - Crash When
+  Initializing !llvm.ptr.
+
+- [Issue #3816](https://github.com/modularml/mojo/issues/3816) - Ternary
+  if-operator doesn't propagate origin information.
+
+- [Issue #3815](https://github.com/modularml/mojo/issues/3815) -
+  [BUG] Mutability not preserved when taking the union of two origins.
+
+- [Issue #3829](https://github.com/modularml/mojo/issues/3829) - Poor error
+  message when invoking a function pointer upon an argument of the wrong origin
+
+- [Issue #3830](https://github.com/modularml/mojo/issues/3830) - Failures
+  emitting register RValues to ref arguments.
+
 - The VS Code extension now auto-updates its private copy of the MAX SDK.
 
 - The variadic initializer for `SIMD` now works in parameter expressions.
@@ -557,7 +682,7 @@ what we publish.
 - Error messages that include type names no longer include inferred or defaulted
   parameters when they aren't needed.  For example, previously Mojo complained
   about things like:
-  
+
   ```plaintext
   ... cannot be converted from 'UnsafePointer[UInt, 0, _default_alignment::AnyType](), MutableAnyOrigin]' to 'UnsafePointer[Int, 0, _default_alignment[::AnyType](), MutableAnyOrigin]'
   ```
@@ -570,3 +695,6 @@ what we publish.
 
 - Tooling now prints the origins of `ref` arguments and results correctly, and
   prints `self` instead of `self: Self` in methods.
+
+- The LSP and generated documentation now print parametric result types
+  correctly, e.g. showing `SIMD[type, simd_width]` instead of `SIMD[$0, $1]`.