Skip to content

Commit

Permalink
CLDR-17566 Converting Other Dev Pages (#4016)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chpy04 @conradarcturus
chpy04 authored and conradarcturus committed Sep 25, 2024
1 parent e152e08 commit 2f6f3ba
Show file tree
Hide file tree
Showing 5 changed files with 326 additions and 0 deletions.
169 changes: 169 additions & 0 deletions docs/site/development/development-process.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
title: Handling Tickets (bugs/enhancements)
---

# Handling Tickets (bugs/enhancements)

### Filing tickets

1. You can add set other fields, but don't change the Owner. That way the committee sees the incoming tickets (those marked as Owner: somebody).
2. ***If you really have to fix a bug right away, file it and send a notice to cldr\-dev explaining what you are doing and why. Otherwise, file the bug, wait for the next Wednesday meeting for discussion and approval.***

### Pre\-Assessment for Weekly Triage

*There is a pre\-assessment of tickets to make the triage flow faster. This pre\-assessment should be done off\-line prior to every Wednesday in time for the TC triage. DO NOT fix a bug until it's been approved by the TC in triage.*

*The triage is a part of Monday and Wednesday meetings.*

1. Ticket comes in, and the default is **Priority**\=assess, **Milestone**\=to\-assess
1. If user sets Component (we always should!) automatically assigns the Owner based on the component owner for the pre\-assessment. \[Add link to Components and Owner]
2. *At this point the Owner function is really as an assessor.*
3. If user does not select the Component, it remains for the group TC triage with Component\=to\-assess, Owner\=anybody. These tickets will be assessed after all the pre\-assessed tickets have been triaged.
2. All TC members, look at [To\-assess by Owner / Component](https://unicode.org/cldr/trac/report/100) before each triage day.
1. Assess the **to\-assess** tickets assigned to you.
2. You can close bugs as duplicate or if user misunderstanding if it is very clear without committee discussion. Always include a comment if you close the ticket.
3. If the component is wrong, change component and reassign to the right component owner.
1. (TODO: copy components to that page, and add notes to clarify; if possible, link to list of components \+ descriptions at top of new ticket). http://cldr.unicode.org/index/bug\-reports
4. Add your assessment information:
1. Change **Milestone** to “assessed”
1. Update Priority, Phase, Component as you'd recommend.
2. Add in comments your recommendation for the Owner.
3. Add additional comments as necessary for other recommendations (like “close as dup”, “maint”, in design, etc)
3. If a committee member files the ticket (or sees a ticket they want to assess), they can do the assessment and follow the same process as the Owner/Delegator to bring to group triage.
1. Committee members can also request to take a ticket by email; that is assumed to be ok if at least one member confirms and nobody disagrees, or 2 working days pass
2. The committee can also decide the fate of Milestone\=to\-assess tickets, typically where someone adds them to the agenda.
4. TC triage meeting, first review those Milestone\=**assessed**.
1. Follow the triage practice by making changes to all fields, Owner, Component, Priority, … or closing the ticket.
2. Update Milestone to one of the following (VV \= the current milestone, eg 35\)
1. **VV** if the (new) Owner agrees that it is a priority — and has some level of commitment to fix during release
2. **VV\-optional**, eg 35\-optional
1. A **future** milestone
3. Triage decides whether it's for Design or Accepted. (**design** indicates for more discussion needed. See design section below.).
5. Other ticket handling practices:
1. There is no commitment to doing a Milestone\=**VV\-optional** ticket. If someone else wants there to be some level of commitment, they should ask to be the Owner, and make the ticket non\-optional.
2. If a ticket has multiple owners, the Notes must describe who is doing what. Otherwise it needs to be split into multiple tickets.
3. if the ticket should be handled in the survey tool there are two options:
1. If to be supervised by TC, set Owner\=\<PM\>, Component\=fix\-in\-survey\-tool. The PM will coordinate with other PMs to bring the issue to the attention of vetters, and check the progress before Resolution.
2. Otherwise return to sender, closed as fix\-in\-survey\-tool

### Design

When a ticket is in design, the owner is responsible for bringing back to the committee to approve the design before any lasting (aside from tests, instrumentation, etc.) work is checked in.

1. The Owner is responsible for documenting the results of the discussion in the TC in comments in the ticket.
2. The Reviewer is responsible for verifying that the design was accepted by the TC before accepting.

### Phases


| | |
|---|---|
| dsub | The ticket should be completed before submission starts. |
| dvet | The ticket should be completed before vetting starts |
| rc | The ticket must be completed before **Alpha — Final Data candidate** . No change to data affecting ICU thereafter. Other dtd, data, spec, docs, tool changes allowed. |
| spec-beta | The ticket must be completed before **Beta — Final Candidate** . No dtd or data changes allowed thereafter. Docs, charts, spec changes allowed (= ICU release candidate) |
| final | The ticket must be completed before **Release** ( = ICU Release) |

### Assignees

1. Assignees periodically review and take care of their tickets.
1. Go to http://unicode.org/cldr/trac/report/61 for **My Tickets**
2. ~~**design:**~~ ~~You must go back to the committee with the completed design before checking anything in. For example, if the ticket doesn't describe an exact DTD structure, then add the proposed structure to the ticket in a comment, and send an email to the committee asking whether anyone objects.~~
3. ~~**assess:**~~ ~~Tickets marked "assess" need to be evaluated for priority (or whether to do them at all). Send your suggested disposition to the cldr group by email.~~
1. **duplicate:** If the ticket is a duplicate, any extra information is copied to the other ticket, an xref is set in both, and the ticket is returned.
2. **splitting:**
1. If the ticket requires separate phases, such as a change to the spec, then a separate ticket is filed, with xrefs set in both.
2. The owner can carry over all the triage acceptance including Owner, Component, etc.
1. If part of a ticket cannot be completed in the release:
1. Set the milestone to the release number
2. Add a comment indicating what part of the ticket was done, and what part wasn't.
3. Set a reviewer.
4. Create a new ticket for the remaining work, with an xref to the old bug.
3. **problems:**
1. If the ticket can't be done due to lack of time, or is being downgraded in priority from major or above to below major, send an email to the cldr group.
2. If during the course of doing the ticket, the person runs up against a problem, then send a message to the cldr group. Examples:
- The description doesn't work
- Another mechanism looks better

### DTD Changes

- **If you are making any DTD changes, please follow the instructions on** [**Updating DTDs**](https://cldr.unicode.org/development/updating-dtds)**.**

### Testing!

- Add unit tests for changes you make, then
- **Make sure to run the tests in** [**Running Tests**](https://cldr.unicode.org/development/running-tests)**!**

Skipping test failures

If there is a test failure that is due to a bug that cannot be fixed right now (eg it requires a data change, but it is past the data freeze), then use the logKnownIssue() method to disable the test. See http://site.icu-project.org/setup/eclipse/time for details, and look in the CLDR test code for some examples of usage.

### Survey Tool in Production Phase!

1. **Before** you make a commit, add a line to the Issues spreadsheet below ([Spreadsheet View](https://docs.google.com/spreadsheets/d/100_r1jobwFCTUdAafc2Ol38UHQn93OIZl5Qmw_Y_5_k/edit#gid=3)), with status OPEN, bug number, short desc.
- *Don't do this if there is a status\=PUSHING*
2. When you're ready for checking, add the commit number to your line, send a message to a designee (cc cldr\-dev) and change the status to CHECK, add testing description (what to check, links if possible).
3. The Designee is normally someone who is familiar with the Survey Tool UI, and must be notified when the line is added. The goal is to check out smoke test to make sure that the change:
1. doesn't make anything worse (with a quick sanity check: if so, mark as Bad, and the change needs to be reverted or fixed before pushing to production), AND
2. does what it was supposed to do as designed per spec or comments in the ticket (if not, mark as Incomplete, and take the ticket out of State\=reviewing; but not a blocker for pushing to production)
3. Capture any necessary information on the Information Hub: resolved items, new feature description, etc...
4. For code changes, the Owner should also:
1. assign and notify a Reviewer
2. add a note to the "How to test / comments" column with Reviewer\=XXX, and whether the changelists need review before a push to production (should be done for any trickier code).
3. if the ticket is State\=reviewing (normal case), the Reviewer can then close the ticket.
5. Designee changes status to **READY**, or communicates problems back to you.

***Once the statuses are all READY, anyone can push to production:***

1. ***Important!*** *Make sure the statuses are all PUSHED or READY and that the "Last Built Rev" isn't later than any items on the list*
1. *If there are any untested commits, double check the [timeline](http://unicode.org/cldr/trac/timeline) and make sure something isn't slipping in!*
2. ***Check*** [http://unicode.org/cldr/trac/timeline?changeset\=on\&build\=on\&daysback\=8](http://unicode.org/cldr/trac/timeline?changeset=on&build=on&daysback=8) to verify that no changes "slipped in"
3. ***Add a line PUSHING***
4. ***Push to production***
5. *If there were noticeable changes, put them in* [*http://cldr.unicode.org/index/survey\-tool\#TOC\-Latest\-Updates*](http://cldr.unicode.org/index/survey-tool#TOC-Latest-Updates) ***(move the old items up to Tool Updates).***
6. *If it was a Known Bug, remove from* [*https://sites.google.com/site/cldr/index/survey\-tool/known\-bugs*](https://cldr.unicode.org/index/survey-tool/faq-and-known-bugs)***.***
7. ***Change status of all READY and PUSHING items to PUSHED.***
8. ***You can delete some older items that are no longer relevant.***
9. ***If the spreadsheet data seems stale, switch to the BuildsCheckins tab, and increment the 'to update' cell. \[ If anyone knows a better way to structure the spreadsheet, please feel free.. \-srl]***

[Survey Tool Issues](https://docs.google.com/spreadsheets/d/0AqRLrRqNEKv-dF9DdVRPVmhHdzhheDliOEpLSUhObXc/edit)

### Checkin

1. All commits must have as their first line: "CLDR\-XXX \<description\>", where XXX is the ticket number.
2. **Don't mark the bug as fixed! Instead,**
1. Once the ticket is done, assign a reviewer.
- *Send a message to the reviewer if the review should be done soon.*

### Reviewers

1. On "Available Reports", click on [My Reviews](http://unicode.org/cldr/trac/report/21).
2. *For each of your tickets to review, open it and do the following:*
3. First read the description *and* comments/replies in the original ticket, since they may contain changes or additions, and also sometimes alert you to changes not captured by the diff tool.
1. In the top right, under View Tickets, you'll see "Review \<x\> commits." Click on that to see the changed files. (Often best to to see side\-by\-side, with right\-click \> open in new window.)
2. In the **Changes** column, click on each of the items (eg, [edit](http://unicode.org/cldr/trac/changeset?old=11625&old_path=trunk%2Ftools%2Fcldr-apps&new_path=trunk%2Ftools%2Fcldr-apps&new=11627)) in each of the cells, and make sure that the implementation matches the description.
3. For data tickets, the goal is to verify that the data in the ticket matches what is entered in.
1. For spec tickets, it is often easier to go to the [Modifications section](http://unicode.org/repos/cldr/trunk/specs/ldml/tr35.html) of the latest proposed spec update, search for the modifications entry with the ticket number for the change that you are reviewing, and then click in that entry’s link to the relevant portion of the spec. The modifications in that section will be shown in yellow, and that is what you need to review.
4. Once you are done, go back to the original ticket (you can click on it at the top), and hit "Modify Ticket" near the bottom.
1. If the implementation looks good:
- click "REVIEWER: Close as fixed", then
- click "Submit changes"
5. If any problems are found
- add a comment to original ticket describing the problems you found
- click "back to owner"
- click "Submit changes"
- if time is short (near the end of the release), send an email to the owner also.
6. Hit "Submit changes"
4. If any issues come up or the topic needs general review, send a message to the [email protected] list.

### Releasers

1. All reviewers should be done well before the end of the release, so that any problems can be taken care of.
2. At release time, all the tickets with status "fixed" are changed to "closed".

### Start of Release

1. The future folder tickets are moved to the discuss folder
2. Unscheduled tickets (with no release number) are re\-evaluated.

![Unicode copyright](https://www.unicode.org/img/hb_notice.gif)
128 changes: 128 additions & 0 deletions docs/site/development/maven.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: Maven Setup
---

# Maven Setup

## Introduction

For a number of reasons, CLDR has switched to [Maven](https://maven.apache.org/).

The purpose of this document is to assist with initial configuration of Maven.

CLDR pulls pre\-release [ICU](https://icu-project.org)4J jars from ICU's GitHub Maven repository.

At present, GitHub requires authentication even for publicly accessible repositories.

The GitHub documentation covering this topic is https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages and will be referred to.

## Getting Started \- GitHub token

We are going to create a token. A token is used like a password, and should be kept secret as one. You can revoke a token independently from all other tokens, so we will create a token specifically for this use.

1. go to https://github.com/settings/tokens \- you may need to login with a 2nd factor.
2. click "generate new token".
- update the Note, something you will remember such as "Maven settings on my laptop"
- give the token "**read:packages**" scope (permission).
- Click the "Generate Token" button at the bottom.
- You will see the new token (random numbers and letters) at the top of the page. Copy it down for the following steps, but **you will not need to save it permanently.**
- You're done with this page now.

## Non\-Eclipse

### Installing Maven

You can run "mvn \-\-version" from the command line to see if Maven is already installed. If you see "Apache Maven 3…" then you are ready to go.

Otherwise, install the "maven" package from your OS or other package manager, or see instructions under https://maven.apache.org/

- Mac brew.sh: ```brew install maven```
- Linux: ```sudo apt install maven```

### Configuring Maven

It might be helpful to refer to the [GitHub documentation](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages) and the [Maven documentation](https://maven.apache.org/settings.html#Servers) for settings during this step.

The file you will be modifying is .m2/settings.xml (the .m2 directory is in your HOME directory, create it if it does not exist).

If the file doesn't exist, create it with this content. If it does exist, add the \<server\> stanza into the \<servers\> section.

Keep the id "githubicu" as it is. (The id "githubcldr" is for accessing CLDR's prebuilt maven assets.)

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<id>githubicu</id> <!-- needed for building CLDR -->
<username>your github id</username>
<password>your access token</password>
</server>
<server> <!-- used by ICU and other clients of CLDR -->
<id>githubcldr</id>
<username>your github id</username>
<password>your access token</password>
</server>
</servers>
</settings>
```

### Try It Out

In the CLDR repo root, go into the tools directory and run:

```mvn package```

This will run all tests and create the all\-in\-one **tools/cldr\-code/target/cldr\-code.jar**. See [CLDR Tools](https://cldr.unicode.org/development/cldr-tools) for details on how to use this jar file.

### More details

**Building without running tests:**

```mvn package -DskipTests=true```

**Running specific tests:**

Example to run only one test from the main unit tests and one test in the web tests: (one long command line, two separate parameters)

```
mvn test '-Dorg.unicode.cldr.unittest.testArgs=-f:TestUntimedCounter -n -q'
'-Dorg.unicode.cldr.unittest.web.testArgs=-f:TestMisc -n -q'
```

**Peter's version:**

To run ConsoleCheck for say a specific locale like "fr", I might do (from the top of the CLDR directory):

```
java -DCLDR_DIR=$(pwd) -jar tools/cldr-code/target/cldr-code.jar check -S common,seed -e -z BUILD -f fr
```

**Running a specific tool from Maven:**

```
mvn -DCLDR_DIR=$HOME/src/cldr exec:java -pl cldr-code -Dexec.mainClass=org.unicode.cldr.json.Ldml2JsonConverter -Dexec.args='-p true -r true -t main -m "de"'
```

## Using Eclipse

(note: a screen capture demonstrating this setup is attached to this page.)

1. See also “[Set up Eclipse for Survey Tool](https://docs.google.com/document/d/1wkJsoQXPcGN_dlCzXzwhfjQoq9Mes7VezIRmNrHWV8c/edit)”
2. To run the SurveyTool components you will need the IDE for Enterprise Developers, you can download this from https://www.eclipse.org/downloads/packages/
3. Make sure the config files are set up first ([**3.2** Configuring Maven](https://cldr.unicode.org/development/maven)), and that CLDR is checked out locally from git in some directory.
4. Go to File \-\> Import, choose Maven and import Existing Maven Projects (see image at right)

![image](../images/development/maven1.png)

1. Give the root of your CLDR checkout, and import all projects.
1. If you are not working on the Survey Tool, you may not need the cldr\-apps and cldr\-rdf projects.
2. To run tests, Choose Run As \> Maven test on the top level (**cldr\-all**) project, or on the cldr\-code project, etc.

![image](../images/development/maven2.png)

1. To start up the Survey Tool, right\-click on 'cldr\-apps' and choose 'Run As… Run On Server'. Create a Tomcat 9 server.

![Unicode copyright](https://www.unicode.org/img/hb_notice.gif)
Loading

0 comments on commit 2f6f3ba

Please sign in to comment.