doc/contributing.md - third_party/github/google/emboss - Git at Google

 # Contributing to Emboss

 If you would like to fix a bug or add a new feature to Emboss, great!  This
 document is intended to help you understand the procedure, so that your change
 can land in the main Emboss repository.

 You do not have to take a change all the way from start to finish, either: if
 you can get a design approved, then someone else can implement it much more
 easily.  Conversely, if you are looking for a way to help, you might look for
 existing [feature
 requests](https://github.com/google/emboss/labels/enhancement) that have
 designs or at [open design sketches](design_docs/) that you might be able to
 implement.


 ## All Changes

 Because Emboss is a Google project, in order to submit code you will need to
 sign a [Google Contributor License Agreement
 (CLA)](https://cla.developers.google.com/).

 **IMPORTANT**: if your contribution includes code that is not covered by a
 Google CLA and is not owned by Google, the Emboss project has to follow special
 procedures to include it.  Please let us know ([filing an issue on
 GitHub](https://github.com/google/emboss/issues/new) is probably the easiest
 way) so that we can walk you through the process.  In particular, we generally
 cannot accept any code from StackExchange or similar sites, and any code that
 comes from a non-Google open source project needs to have an acceptable license
 and be committed to the Emboss repository in a specific location.


 ### Updating Build Helper Files

 The Emboss project provides a set of generated files in the `gen/` directory
 that can be used by other build systems (like CMake, GN, etc.) to easily
 include the Emboss compiler and C++ runtime sources.

 These files are generated from a single source of truth: `build.json`.

 -   **`build.json`**: This file, located in the project root, contains the
     canonical lists of source files required for the compiler and the C++
     runtime. It is the only file in this system that should be manually
     edited, though it is typically updated via a script.

 -   **`gen/`**: This directory contains the generated helper files. **Do not
     edit these files directly**, as they will be overwritten.

 If you change the dependencies of the Emboss compiler or runtime in the Bazel
 build system, you will need to update `build.json` and regenerate the helper
 files.

 -   To update `build.json` with the latest sources from Bazel, run:
     ```bash
     ./scripts/build_helpers/manage_build_json.py
     ```

 -   To regenerate the files in `gen/` after modifying `build.json`, run:
     ```bash
     ./scripts/build_helpers/generate_build_files.py
     ```

 A CI check is in place to ensure that `build.json` is always in sync with the
 Bazel build. If this check fails, you will need to run the `manage_build_json.py`
 script and commit the changes.


 ### How-To Guides

 This document covers the process of getting a change into the main Emboss
 repository — i.e., what you need to do to get your change into
 [the main Emboss repository](https://github.com/google/emboss/).

 [How to Implement Changes to Emboss](how-to-implement.md) has an overview of
 how to make code changes to Emboss.

 [How to Design Features for Emboss](how-to-design.md) has an overview of what
 to think about during your design.


 ### Bug Fixes vs New Features

 The general process for bug fixes and new features is the same, but bug fixes
 usually require less design work, and therefore can go through lighter
 processes.


 ## Very Small Changes

 If you have a tiny change — for example,  making a fix that does not change the
 design of `embossc` — you can jump directly into coding.

 This process works best if your change is small and not likely to be
 controversial, or if you have already completed [the steps for small
 changes](#small-changes).

 1.  [Code up your proposed change](how-to-implement.md) and open a [pull
     request
     (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
     to [the main Emboss repository](https://github.com/google/emboss/).  If you
     have not completed [the steps for small changes](#small-changes), this
     gives the Emboss maintainers something more concrete to look at, but you
     may end up doing more work if your initial proposal turns out to be the
     wrong approach.

 2.  The Emboss maintainers will review your PR, and may request changes.  Don't
     be discouraged if your PR is not immediately accepted — even PRs that
     maintainers send to each other often have requests for changes!  We want
     the Emboss code to be high-quality, which means helping you make your code
     better.

 3.  Once your PR reaches a point where it is good enough, an Emboss maintainer
     will merge it into the Emboss repository.


 ## Small Changes

 If your change is small, but still requires some design work — for example,
 adding a new utility function in the C++ runtime library, or making a bug fix
 that involves re-structuring some of the `embossc` code — it is usually best to
 get some feedback before you start coding.

 1.  [File an issue on GitHub](https://github.com/google/emboss/issues/new), if
     there is not an issue already.  It is best to use the *problem you want to
     solve* for the issue title and description, and then propose your design in
     a comment.

 2.  Once the Emboss maintainers have had a chance to review your proposal and
     agree on the general outline, follow [the procedure for very small
     changes](#very-small-changes).


 ## Medium and Large Changes

 If you have a medium or large change — for example, introducing a new pass in
 `embossc`, adding a new data type, adding a new operator to the Emboss
 expression language, making a cross-cutting refactoring of `embossc`, etc. —
 then you should start by writing a *design sketch*.

 A design sketch is, basically, an informal design doc — it covers the topics
 that a design doc would cover, but may have open questions or alternatives that
 haven't been locked down.

 1.  [File an issue on GitHub](https://github.com/google/emboss/issues/new), if
     there is not an issue already.  It is best to use the *problem you want to
     solve* for the issue title and description.

 2.  Look at [existing design sketches](design_docs/) and [archived design docs
     for changes that have already landed](design_docs/archive/) to get a feel
     for what should be in a design sketch.

 3.  If you have not already done so, read [How to Design Features for
     Emboss](how-to-design.md).

 4.  Write a draft design sketch for your change, and open a pull request
     against [the main Emboss repository](https://github.com/google/emboss/).

 5.  It is very likely that your design sketch will need revision before it is
     accepted.  If it does, do not be discouraged — we want your change to
     succeed!

 6.  Once your design sketch has been accepted, you can move on to
     implementation, following (more or less) the same procedure you would
     follow for [small](#small-changes) or [very small
     changes](#very-small-changes).  Depending on the complexity of the change,
     you may need to split your implementation into multiple changes.
	# Contributing to Emboss

	If you would like to fix a bug or add a new feature to Emboss, great! This
	document is intended to help you understand the procedure, so that your change
	can land in the main Emboss repository.

	You do not have to take a change all the way from start to finish, either: if
	you can get a design approved, then someone else can implement it much more
	easily. Conversely, if you are looking for a way to help, you might look for
	existing [feature
	requests](https://github.com/google/emboss/labels/enhancement) that have
	designs or at [open design sketches](design_docs/) that you might be able to
	implement.


	## All Changes

	Because Emboss is a Google project, in order to submit code you will need to
	sign a [Google Contributor License Agreement
	(CLA)](https://cla.developers.google.com/).

	IMPORTANT: if your contribution includes code that is not covered by a
	Google CLA and is not owned by Google, the Emboss project has to follow special
	procedures to include it. Please let us know ([filing an issue on
	GitHub](https://github.com/google/emboss/issues/new) is probably the easiest
	way) so that we can walk you through the process. In particular, we generally
	cannot accept any code from StackExchange or similar sites, and any code that
	comes from a non-Google open source project needs to have an acceptable license
	and be committed to the Emboss repository in a specific location.


	### Updating Build Helper Files

	The Emboss project provides a set of generated files in the `gen/` directory
	that can be used by other build systems (like CMake, GN, etc.) to easily
	include the Emboss compiler and C++ runtime sources.

	These files are generated from a single source of truth: `build.json`.

	- `build.json`: This file, located in the project root, contains the
	canonical lists of source files required for the compiler and the C++
	runtime. It is the only file in this system that should be manually
	edited, though it is typically updated via a script.

	- `gen/`: This directory contains the generated helper files. **Do not
	edit these files directly**, as they will be overwritten.

	If you change the dependencies of the Emboss compiler or runtime in the Bazel
	build system, you will need to update `build.json` and regenerate the helper
	files.

	- To update `build.json` with the latest sources from Bazel, run:
	```bash
	./scripts/build_helpers/manage_build_json.py
	```

	- To regenerate the files in `gen/` after modifying `build.json`, run:
	```bash
	./scripts/build_helpers/generate_build_files.py
	```

	A CI check is in place to ensure that `build.json` is always in sync with the
	Bazel build. If this check fails, you will need to run the `manage_build_json.py`
	script and commit the changes.


	### How-To Guides

	This document covers the process of getting a change into the main Emboss
	repository — i.e., what you need to do to get your change into
	[the main Emboss repository](https://github.com/google/emboss/).

	[How to Implement Changes to Emboss](how-to-implement.md) has an overview of
	how to make code changes to Emboss.

	[How to Design Features for Emboss](how-to-design.md) has an overview of what
	to think about during your design.


	### Bug Fixes vs New Features

	The general process for bug fixes and new features is the same, but bug fixes
	usually require less design work, and therefore can go through lighter
	processes.


	## Very Small Changes

	If you have a tiny change — for example, making a fix that does not change the
	design of `embossc` — you can jump directly into coding.

	This process works best if your change is small and not likely to be
	controversial, or if you have already completed [the steps for small
	changes](#small-changes).

	1. [Code up your proposed change](how-to-implement.md) and open a [pull
	request
	(PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
	to [the main Emboss repository](https://github.com/google/emboss/). If you
	have not completed [the steps for small changes](#small-changes), this
	gives the Emboss maintainers something more concrete to look at, but you
	may end up doing more work if your initial proposal turns out to be the
	wrong approach.

	2. The Emboss maintainers will review your PR, and may request changes. Don't
	be discouraged if your PR is not immediately accepted — even PRs that
	maintainers send to each other often have requests for changes! We want
	the Emboss code to be high-quality, which means helping you make your code
	better.

	3. Once your PR reaches a point where it is good enough, an Emboss maintainer
	will merge it into the Emboss repository.


	## Small Changes

	If your change is small, but still requires some design work — for example,
	adding a new utility function in the C++ runtime library, or making a bug fix
	that involves re-structuring some of the `embossc` code — it is usually best to
	get some feedback before you start coding.

	1. [File an issue on GitHub](https://github.com/google/emboss/issues/new), if
	there is not an issue already. It is best to use the *problem you want to
	solve* for the issue title and description, and then propose your design in
	a comment.

	2. Once the Emboss maintainers have had a chance to review your proposal and
	agree on the general outline, follow [the procedure for very small
	changes](#very-small-changes).


	## Medium and Large Changes

	If you have a medium or large change — for example, introducing a new pass in
	`embossc`, adding a new data type, adding a new operator to the Emboss
	expression language, making a cross-cutting refactoring of `embossc`, etc. —
	then you should start by writing a design sketch.

	A design sketch is, basically, an informal design doc — it covers the topics
	that a design doc would cover, but may have open questions or alternatives that
	haven't been locked down.

	1. [File an issue on GitHub](https://github.com/google/emboss/issues/new), if
	there is not an issue already. It is best to use the *problem you want to
	solve* for the issue title and description.

	2. Look at [existing design sketches](design_docs/) and [archived design docs
	for changes that have already landed](design_docs/archive/) to get a feel
	for what should be in a design sketch.

	3. If you have not already done so, read [How to Design Features for
	Emboss](how-to-design.md).

	4. Write a draft design sketch for your change, and open a pull request
	against [the main Emboss repository](https://github.com/google/emboss/).

	5. It is very likely that your design sketch will need revision before it is
	accepted. If it does, do not be discouraged — we want your change to
	succeed!

	6. Once your design sketch has been accepted, you can move on to
	implementation, following (more or less) the same procedure you would
	follow for [small](#small-changes) or [very small
	changes](#very-small-changes). Depending on the complexity of the change,
	you may need to split your implementation into multiple changes.